ACC: How to Use the ReplicationConflictFunction Property

Exención de responsabilidades de contenido KB retirado

Este artículo se refiere a productos para los que Microsoft ya no ofrece soporte técnico. Por tanto, el presente artículo se ofrece "tal cual" y no será actualizado.

Advanced: Requires expert coding, interoperability, and multiuser skills.


Summary

This article show you how to use the ReplicationConflictFunction property in a database replica set so that you can create a custom procedure to resolve synchronization conflicts.

More Information

When you use replicated databases in Microsoft Access, you may encounter synchronization errors from time to time. Microsoft Access includes a Conflict Resolver wizard to help you resolve those conflicts when they occur.


However, you may want to create your own procedure to help users resolve synchronization conflicts. Also, the Microsoft Access Developer's Toolkit license agreement does not permit you to distribute wizards with your run-time applications; therefore, you must create your own conflict resolution procedure if your run-time application includes replicated databases.


The ReplicationConflictFunction property enables you to use a custom procedure to resolve conflicts instead of using the Conflict Resolver wizard. The procedure that you create to resolve conflicts must be in a replicable module in the Design Master.

Creating a Custom Conflict Resolver


Your custom procedure must be able to process three types of errors:

  • Synchronization conflicts
  • Synchronization errors
  • Design errors

Synchronization Conflicts


Synchronization conflicts occur when one record in a table is updated at two or more different replicas. Even if the changes are made to different fields in the record, the Microsoft Jet database engine treats it as a conflict. The Jet database engine does not try to resolve the conflict. Instead, it uses an algorithm to select one version of the record as the official change, and it stores the other version in a conflict table.


Conflict tables are named <tablename>_Conflict, where <tablename> is the table in which the conflict occurred. You can detect conflicts using Visual Basic code by looking for the ConflictTable property of a table. The following portion of a procedure checks for the existence of conflict tables in a replica database:

   Sub ViewSyncConflict()
Dim Db As DATABASE
Dim Td As TableDef
Dim i as Integer
Set Db = CurrentDb
' Step backward through the TableDefs collection so you
' do not miss any tables when you delete conflict tables.
For i = Db.TableDefs.Count - 1 to 0 Step -1
Set Td = Db.Tabledefs(i)
If (Td.ConflictTable <> "") Then
' Open a recordset based on the conflict table.
' Insert code to do conflict resolution.
' Delete the conflicting record when you are done.
' Delete the conflict table when all its records are deleted.
' Set the ConflictTable property to "".
End If
Next i
End Sub

Synchronization Errors

  • A table-level validation rule is applied and other replicas have data that does not satisfy the rule.
  • A duplicate key error occurs because two different replicas entered the same primary key into a table.
  • A referential integrity error occurs because a primary table record is deleted in one replica, and a record is added to a related table in another replica.
  • A record is locked when synchronization occurs.
Synchronization errors are recorded in the MSysErrors table and are replicated to all members of the replica set. Once you have corrected the errors, the Jet database engine automatically removes the error records during a subsequent synchronization.


Open the MSysErrors table to see what errors occurred. The following portion of a procedure displays the synchronization errors in the MSysErrors table:

  Sub ViewSyncError()
Dim Db As DATABASE
Dim Rs As Recordset
Dim MsgString As String
On Error GoTo ErrorHandler
Set Db = CurrentDb
Set Rs = Db.OpenRecordset("MSysErrors", dbOpenSnapshot)
Rs.MoveLast
If Rs.RecordCount > 0 Then
Rs.MoveFirst
Do Until Rs.EOF
' Build the error message string.
MsgString = "Table ID: " & Rs!TableGUID & vbCr
MsgString = MsgString & "Record ID: " & Rs!RowGUID & vbCr
MsgString = MsgString & "Operation: " & Rs!Operation & vbCr
MsgString = MsgString & "Failed Because: " & Rs!ReasonText
MsgBox MsgString
Rs.MoveNext
Loop
End If

ExitProc:
Exit Sub

ErrorHandler:
' If the MSysErrors table is empty...
If Err.Number = 3021 Then
Resume ExitProc
' display any other error that occurs.
Else
MsgBox Err.Description
Resume ExitProc
End If
End Sub

Design Errors


A design error occurs when a local object exists with the same name as a replicable object in the Design Master. For example, if a user at a replica creates a local form called Form1, and you create a replicable form in the Design Master called Form1, synchronization fails. The design error is recorded in a system table called MSysSchemaProb. The records in MSysSchemaProb are automatically deleted when the conflict is resolved and the design change is successfully synchronized.


The following sample procedure checks for the existence of the MSysSchemaProb table, and displays the design error:

  Sub ViewDesignError()
Dim Db As DATABASE
Dim Rs As Recordset
Dim MsgString As String
On Error GoTo ErrorHandler
Set Db = CurrentDb
Set Rs = Db.OpenRecordset("MSysSchemaProb", dbOpenSnapshot)
Rs.MoveFirst
Do Until Rs.EOF
' Build the error message string.
MsgString = "Operation: " & Rs!Command & vbCr
MsgString = MsgString & "Failed Because: " & Rs!ErrorText
MsgBox MsgString
Rs.MoveNext
Loop

ExitProc:
Exit Sub

ErrorHandler:
' If the MSysSchemaProb table does not exist.
If Err.Number = 3078 Then
Resume ExitProc
' If the MSysSchemaProb table is empty.
ElseIf Err.Number = 3021 Then
Resume ExitProc
' Display any other error that occurs.
Else
MsgBox Err.Description
Resume ExitProc
End If
End Sub

Putting It All Together


After you have decided how you want to handle each type of synchronization error, create the custom function to use when conflicts occur. The following example combines the sample procedures in each of the earlier sections into a single function:

   Function MyCustomFunction()
ViewSyncConflict
ViewSyncError
ViewDesignError
End Function

Setting the ReplicationConflictFunction Property


You can set the ReplicationConflictFunction property programmatically or through the user interface. When you set the property programmatically, you may have to add ReplicationConflictFunction to the Properties collection of the database first, and then set its value.

Setting the ReplicationConflictFunction Programmatically

  1. Open the Design Master database for the replica set.
  2. Create a module and type the following procedure:
          Sub SetCustomFunction(FunctionName As String)
    Dim Db As DATABASE, Ctr As Container, Doc As Document
    Dim Prp As Property
    On Error GoTo ErrorHandler
    Set Db = CurrentDb
    Set Ctr = Db.Containers!Databases
    ' Set Document variable pointing to user defined document.
    Set Doc = Ctr.Documents!UserDefined
    ' Set the ReplicationConflictFunction property if it exists.
    Doc.Properties!ReplicationConflictFunction = FunctionName
    Exit Sub

    ErrorHandler:
    ' If the property does not exist...
    If Err.Number = 3270 Then
    ' create ReplicationConflictFunction property and set its
    ' value.
    Set Prp = Doc.CreateProperty("ReplicationConflictFunction", _
    dbText, FunctionName)
    ' Append the new property to the collection.
    Doc.Properties.Append Prp
    ' Resume the main procedure.
    Resume Next
    Else
    ' Display any other error that occurs.
    MsgBox Err.Number & ": " & Err.Description, vbCritical
    End If
    End Sub
  3. To test this function, type the following line in the Debug window, and then press ENTER:
    SetCustomFunction("MyCustomFunction()")

Setting the ReplicationConflictFunction Through the User Interface

  1. Open the Design Master database for the replica set.
  2. On the File menu, click Database Properties.
  3. In the <DatabaseName> Properties dialog box, click the Custom tab.
  4. Set the following properties:
    Name: ReplicationConflictFunction
    Type: Text
    Value: MyCustomFunction()
  5. Click OK to close the Properties dialog box.
For more information about using replication in your database, please see the following articles in the Microsoft Knowledge Base for instructions on obtaining the Microsoft Jet Database Replication white paper:
138828 ACC95: Microsoft Jet Replication White Paper Available in Download Center



164553 ACC97: Jet 3.5 Replication White Paper Available in Download Center
Propiedades

Id. de artículo: 158930 - Última revisión: 10/11/2006 - Revisión: 1

Comentarios