Synchronizing Databases
Page 5 of 11

Steps of the Refresh Operation

The refresh operation goes through the following steps:

  1. Provisional transactions are applied at the source in the order in which they were applied at the target. See Applying Provisional Transactions at the Source for possible outcomes of this step.
  2. All changes to the source since this target's last refresh, including successful transactions just applied from this target, are copied to the target.

If the refresh completes successfully:

  • Target data is in agreement with source data.
  • Transactions that committed at the target before this refresh are no longer provisional. A provisional change becomes durable after it applies successfully at the source. A change is removed from the target if it is rejected at the source.

Applying Provisional Transactions at the Source

When a provisional transaction is sent to the source, one of the following occurs:

Cloudscape synchronization keeps databases internally consistent and in agreement even if errors occur.

NOTE: By using work units, you can control when each type of error is raised. See Error Handling in Work Units for more details.

NOTE: You can retrieve failed transaction information from SYSERRORS using the printFailedTransaction method. For more information, see Debugging Synchronized Systems.

Scenario 1: The Transaction Applies Successfully

Since source and target data are similar, provisional target transactions typically apply successfully at the source. If they do:

  1. The transaction is applied durably at the source.
  2. Changes from this transaction are written durably at the target at the end of the refresh cycle.

Scenario 2: A Consistency Error Occurs

A consistency error occurs when the provisional transaction, if applied at the source, would cause the source to become inconsistent. For example, a consistency error occurs if the transaction violates a source check constraint. Consistency errors typically occur because the source data has changed since this target's last refresh.

When consistency errors are encountered during refresh, the offending provisional transaction fails, but the refresh continues.

If a provisional transaction is rejected at the source to avoid a consistency violation:

  1. The offending provisional transaction aborts.
  2. The failed transaction is recorded in the SYSERRORS table.
  3. The refresh resumes with the next provisional transaction.
  4. Changes attempted by the failed transaction are rolled back from the target's user tables after the refresh.

Cloudscape provides utilities to show descriptions of consistency errors. These utilities are in COM.cloudscape.types.ErrorInfo.

Removing Records from SYSERRORS

In some cases, you may want to remove records from the SYS.SYSERRORS table. The deleteError method in COM.cloudscape.database.Database can be used to delete a specific error using its errorID.

For example, the following ij statement would remove the error from SYS.SYSERRORS whose errorID is a352c053.

SELECT Factory.getDatabaseOfConnection().deleteError(
    Factory.getSystemOfConnection().
    getUUIDFactory().recreateUUID(
    'a352c053'))
FROM SYS.SYSERRORS;

See the Cloudscape Reference Manual for reference information about the SYSERRORS table.

Scenario 3: An Environmental Error Occurs and the Transaction Remains Provisional

When a refresh encounters environmental errors at the source, the transaction remains provisional.

Examples of environmental errors are:

  • out of memory
  • method alias name not found
  • unresolvable deadlock
  • source machine crash
  • severe coding error

When an environmental error occurs.

  1. The refresh halts.
  2. The provisional transaction remains provisional. (Even `successful' transactions that have not yet applied at the source remain provisional.)
  3. The transaction is re-sent to the source at the next refresh.

If an environmental error occurs, the system administrator should address the problem immediately.

Applying Source Data to the Target

At the end of a successful refresh operation, the target data is replaced with a copy of the source data. (This is done efficiently; only data changes are actually sent through the wire.) Since source data changes simply overwrite target data, agreement between source and target is assured, no matter what errors occurred during the refresh or how they were handled.

Target Refresh Failures

Rarely, a refresh may complete successfully at the source, but fail on the originating target during the refresh reply. This can occur when the connection fails between the target and source during refresh, or when a publication has been poorly designed.

Connection Failure

If a refresh operation completes at the source but the connection fails during the refresh reply, the refresh fails with an I/O error and the target is left in the same state as before the refresh. Changes made at the source during this refresh endure. The user should refresh again later, and the changed data will reach the target at the target's next successful refresh. The source recognizes changes that were previously applied and does not reapply them.

Other Failure

If a refresh operation completes at the source but fails to apply at the target for a reason other than connection failure, the user should contact the system administrator. The target error message indicates this situation. A likely cause of this situation is a foreign key violation at the target, which can be avoided with proper publication design. See Handling Published Foreign Keys for more details.