Global Script Events
Define global event handlers in the GlobalEvents class in the Global Script. Each global event must have an attribute section called 'GlobalEventsAttribute' specifying the internal event that the function is handling.
GlobalEventsAttribute
An attribute with two parameters, the event name and a help string. This attribute must always be declared when defining an error handler for the Record_OnExecuteError and Replication_OnError events.
Parameter 1: Required. A string containing the event name. The value must match the name of the event being handled.
Parameter 2: Required. A string containing a description or help message for the event handler. This string is not currently used by Syniti DR, but because the parameter is required, you must at least provide an empty string " ".
Record_OnExecuteError
This event occurs whenever an error on execution of a single record occurs. As a writer event, it occurs on target operations, such as INSERT, DELETE, UPDATE. Use the bRetryExecute option to force an attempt to rerun an execute operation on a record when the operation initially fails. For instance, if a single record insert fails with a timeout error, setting bRetryExecute to true and setting values for iSleep and iIteration parameters, might allow the operation to succeed a few milliseconds later. Note that the replication event Record_OnBeforeExecute is generated only once, no matter how many times the record operation is retried using this parameter. Also the replication event Record_OnAfterExecute is generated once only if the record operation succeeds and not at all if the record operation fails.
The GlobalEventsAttribute first parameter must indicate the event name "Record_OnExecuteError".
VB.NET Syntax
<GlobalEventsAttribute("Record_OnExecuteError", "Define a general event for the event OnExecuteError")>
Public Shared Sub MyErrorHandler (ByVal sReplOrGroupName As String,
ByVal recTarget As DBMotoPublic.IRecord,
ByVal e As Exception,
ByRef bRecoverReplication As Boolean,
ByRef bDisableReplication As Boolean,
ByRef bRetryExecute As Boolean,
ByRef iSleep As Integer,
ByVal iIteration As Integer)
Note: Function name 'MyErrorHandler' can be modified.
C# Syntax
[GlobalEventsAttribute("Record_OnExecuteError", "Define a general event for the event OnExecuteError")]
public static void MyErrorHandler(string sReplOrGroupName,
DBMotoPublic.IRecord recTarget,
Exception e,
ref bool bRecoverReplication,
ref bool bDisableReplication,
ref bool bRetryExecute,
ref int iSleep,
int iIteration)
Parameters
|
Name |
Type |
Description |
|
sReplOrGroupName |
String |
Read only. The name of the replication or group that generated the event. |
|
recTarget |
Read only. The object that represents the target record for which the error was generated. You can access specific information in the record using the methods available in the IRecord interface. |
|
|
e |
Exception |
Read only. The VB .NET Exception object for this error. |
|
bRecoverReplication |
Boolean |
The default is False. If set to True, the replication is set to recovery mode |
|
bDisableReplication |
Boolean |
The default is False. If set to True, regardless of the RetryExecute value, the replication exits signaling serror message in the log and disabling the replication. |
|
bRetryExecute |
Boolean |
The default value is False. Set this parameter to True if you want to try the target record operation again before recording the error in the Syniti DR log. For instance, if a single record insert fails with a timeout error, setting bRetryExecute to True and setting a value for the iSleep parameter might allow the operation to succeed a few milliseconds later. The example below demonstrates how to use this parameter. Note that the replication event Record_OnBeforeExecute is generated only once, no matter how many times the record operation is retried using this parameter. Also the replication event Record_OnAfterExecute is generated once only if the record operation succeeds and not at all if the record operation fails. |
|
iSleep |
Integer |
When bRetryExecute is set to True, use this parameter to indicate a delay value before retrying the operation. The value should be in milliseconds. The default value is 0. The example below demonstrates how to use this parameter. |
|
iIteration |
Integer |
Read
only. For use in conjunction with the bRetryExecute parameter.
iIteration keeps track of the number of times the target record
operation is attempted. The start value is 0. When the target
record operation is attempted the first time, this value is set
to 1. The event handler will continue to retry the operation until
bRetryExecute is set to false. The example below demonstrates
how you might avoid an infinite loop on an error. |
VB.NET Example
<GlobalEventsAttribute("Record_OnExecuteError", "Define a general event for the event EventName")>
Public Shared Sub MyErrorHandler (ByVal sReplOrGroupName As String,
ByVal recTarget As DBMotoPublic.IRecord,
ByVal e As Exception,
ByRef bRecoverReplication As Boolean,
ByRef bAbortRecord As Boolean,
ByRef bDisableReplication As Boolean,
ByRef bRetryExecute As Boolean,
ByRef iSleep As Integer,
ByVal iIteration As Integer)
Dim s As String
s = s + "-- Called MyErrorHandler to catch the error in replication or group '"
+ sReplOrGroupName + "'" + Environment.NewLine
s = s + "-- Exception: " + e.ToString() + Environment.NewLine
s = s + "-- Iteration: " + iIteration.ToString()
bRetryExecute = False
' Disable replication if the error is a SQL Server timeout error
If e.Message.IndexOf("System.Data.SqlClient.SqlException: Timeout expired.") == 0 Then
bAbortRecord = True
bDisableReplication = True
s = s + " - Replication disabled"
Else ' retry
If iIteration = 3 Then
bRetryExecute = False
s = s + " - No Retry"
Else
bRetryExecute = True
iSleep = 3000
s = s + " - Try Again after " + (iSleep/1000).ToString() + " seconds."
End If
End If
IGlobalScript.AddLog (s, 1)
End Sub
C# Example
public class GlobalEvents : IGlobalEvents
{
/// <param name="sReplOrGroupName"> </param>
/// <param name="recTarget"></param>
/// <param name="e"></param>
/// <param name="bDisableReplication"></param>
/// <param name="bRetryExecute"></param>
/// <param name="iSleep"></param>
/// <param name="iIteration"></param>
[GlobalEventsAttribute("Record_OnExecuteError", "Define a general event for the event EventName")]
public static void MyErrorHandler(String sReplOrGroupName, DBMotoPublic.IRecord recTarget, Exception e,
ref bool bRecoverReplication, ref bool bAbortRecord, ref bool bDisableReplication,
ref Boolean bRetryExecute, ref int iSleep, int iIteration)
{
String s = null;
s = s + "-- Called MyErrorHandler to catch the error in replication or group '" + sReplOrGroupName + "'"
+ Environment.NewLine;
s = s + "-- Exception: " + e.ToString() + Environment.NewLine;
s = s + "-- Iteration: " + iIteration.ToString();
bRetryExecute = false;
// Disable replication if the error is a SQL Server timeout error
if (e.Message.IndexOf("System.Data.SqlClient.SqlException: Timeout expired.") = 0) {
bAbortRecord = true;
bDisableReplication = true;
s = s + " - Replication disabled";
}
else { // retry
if (iIteration >= 3) {
bRetryExecute = false;
s = s + " - No Retry";
}
else {
bRetryExecute = true;
iSleep = 3000;
s = s + " - Try Again after " + (iSleep / 1000).ToString() + "seconds.";
}
}
IGlobalScript.AddLog(s, 1);
}
Record_OnMappingError
This event occurs whenever an error on mapping of a single record occurs. As a reader event, it occurs on source when mapping operations, such as INSERT, DELETE, UPDATE. Use the bRetryExecute option to force an attempt to rerun a mapping operation on a record when the operation initially fails. For instance, if a single field map fails with a syntax error, setting bRetryExecute to true, might allow the user to change some values in the field and repeat the operation. Note that the replication event Record_OnBeforeMapping is generated only once, no matter how many times the record operation is retried using this parameter. Also the replication event Record_OnAfterMapping is generated once only if the record operation succeeds and not at all if the record operation fails.
The GlobalEventsAttribute first parameter must indicate the event name "Record_OnMappingError".
VB.NET Syntax
Note: Function name 'MyErrorHandler' can be modified.
<GlobalEventsAttribute("Record_OnMappingError", "Define a general event for the event OnMappingError")>
Public Shared Sub MyErrorHandler (ByVal sReplOrGroupName As String,
ByVal recSource As DBMotoPublic.IRecord,
ByVal recTarget As DBMotoPublic.IRecord,
ByVal e As Exception,
ByRef bAbort As Boolean,
ByRef bRecoverReplication As Boolean,
ByRef bDisableReplication As Boolean,
ByRef bRetryExecute As Boolean,
ByRef iSleep As Integer,
ByVal iIteration As Integer)
C# Syntax
[GlobalEventsAttribute("Record_OnMappingError", "Define a general event for the event OnMappingError")]
public static void MyErrorHandler(string sReplOrGroupName,
DBMotoPublic.IRecord recSource,
DBMotoPublic.IRecord recTarget,
Exception e,
ref bool bAbort,
ref bool bRecoverReplication,
ref bool bDisableReplication,
ref bool bRetryExecute,
ref int iSleep,
int iIteration)
Parameters
|
Name |
Type |
Description |
|
sReplOrGroupName |
String |
Read only. The name of the replication or group that generated the event. |
| recSource | IRecord | Read only. The object that represents the source record for which the error was generated. You can access specific information in the record using the methods available in the IRecord interface. |
|
recTarget |
Read only. The object that represents the target record for which the error was generated. You can access specific information in the record using the methods available in the IRecord interface. |
|
|
e |
Exception |
Read only. The VB .NET Exception object for this error. |
| bAbort | Boolean | The default is False. If set to True, the current record is skipped and not replicated. No errors will be shown in the log. |
|
bRecoverReplication |
Boolean |
The default is False. If set to True, the replication is set to recovery mode |
|
bDisableReplication |
Boolean |
The default is False. If set to True, regardless of the RetryExecute value, the replication exits signaling serror message in the log and disabling the replication. |
|
bRetryExecute |
Boolean |
The default value is False. Set this parameter to True if you want to try the target record operation again before recording the error in the Syniti DR log. For instance, if a single record insert fails with a timeout error, setting bRetryExecute to True and setting a value for the iSleep parameter might allow the operation to succeed a few milliseconds later. The example below demonstrates how to use this parameter. Note that the replication event Record_OnBeforeExecute is generated only once, no matter how many times the record operation is retried using this parameter. Also the replication event Record_OnAfterExecute is generated once only if the record operation succeeds and not at all if the record operation fails. |
|
iSleep |
Integer |
When bRetryExecute is set to True, use this parameter to indicate a delay value before retrying the operation. The value should be in milliseconds. The default value is 0. The example below demonstrates how to use this parameter. |
|
iIteration |
Integer |
Read
only. For use in conjunction with the bRetryExecute parameter.
iIteration keeps track of the number of times the target record
operation is attempted. The start value is 0. When the target
record operation is attempted the first time, this value is set
to 1. The event handler will continue to retry the operation until
bRetryExecute is set to false. The example below demonstrates
how you might avoid an infinite loop on an error. |
VB.NET Example
<GlobalEventsAttribute("Record_OnMappingError", "Define a general event for the event EventName")>
Public Shared Sub MyErrorHandler (ByVal sReplOrGroupName As String,
ByVal recSource As DBMotoPublic.IRecord,
ByVal recTarget As DBMotoPublic.IRecord,
ByVal e As Exception,
ByRef bAbort As Boolean,
ByRef bRecoverReplication As Boolean,
ByRef bAbortRecord As Boolean,
ByRef bDisableReplication As Boolean,
ByRef bRetryExecute As Boolean,
ByRef iSleep As Integer,
ByVal iIteration As Integer)
Dim s As String
s = s + "-- Called MyErrorHandler to catch the error in replication or group '"
+ sReplOrGroupName + "'" + Environment.NewLine
s = s + "-- Exception: " + e.ToString() + Environment.NewLine
s = s + "-- Iteration: " + iIteration.ToString()
bRetryExecute = False
' Disable replication if the error is a syntax error
If e.Message.Contains("Error applying the mapping for the target field") Then
bAbortRecord = True
bDisableReplication = True
s = s + " - Replication disabled"
Else ' retry
If iIteration = 3 Then
bRetryExecute = False
s = s + " - No Retry"
Else
bRetryExecute = True
iSleep = 3000
s = s + " - Try Again after " + (iSleep/1000).ToString() + " seconds."
End If
End If
IGlobalScript.AddLog (s, 1)
End Sub
C# Example
public class GlobalEvents : IGlobalEvents
{
/// <param name="sReplOrGroupName"> </param>
/// <param name="recTarget"></param>
/// <param name="e"></param>
/// <param name="bDisableReplication"></param>
/// <param name="bRetryExecute"></param>
/// <param name="iSleep"></param>
/// <param name="iIteration"></param>
[GlobalEventsAttribute("Record_MappingError", "Define a general event for the event EventName")]
public static void MyErrorHandler(String sReplOrGroupName, DBMotoPublic.IRecord recSource, DBMotoPublic.IRecord recTarget, Exception e,
ref bool bAbort, ref bool bRecoverReplication, ref bool bAbortRecord, ref bool bDisableReplication,
sref Boolean bRetryExecute, ref int iSleep, int iIteration)
{
String s = null;
s = s + "-- Called MyErrorHandler to catch the error in replication or group '" + sReplOrGroupName + "'"
+ Environment.NewLine;
s = s + "-- Exception: " + e.ToString() + Environment.NewLine;
s = s + "-- Iteration: " + iIteration.ToString();
bRetryExecute = false;
// Disable replication if the error is a syntax error
if (e.Message.Contains("Error applying the mapping for the target field")) {
bAbortRecord = true;
bDisableReplication = true;
s = s + " - Replication disabled";
}
else { // retry
if (iIteration >= 3) {
bRetryExecute = false;
s = s + " - No Retry";
}
else {
bRetryExecute = true;
iSleep = 3000;
s = s + " - Try Again after " + (iSleep / 1000).ToString() + "seconds.";
}
}
IGlobalScript.AddLog(s, 1);
}
Replication_OnError
This event occurs whenever an error on a replication occurs. Any type of error that is shown in the Replication Monitor as an error or warning icon at the end of the replication operation generates this event. This event is invoked at the end of a refresh or at the end of the mirroring interval, and not at the moment the error happens.
The GlobalEventsAttribute first parameter must indicate the event name "Replication_OnError".
VB.NET Syntax
<GlobalEventsAttribute("Replication_OnError", "Define a general event for the event Replication_OnError")>
Public Shared Sub MyErrorHandler (ByVal sReplOrGroupName As String, ByVal sMessage As String,
ByVal bWillDisable As Boolean, ByVal eReplStatus As enmReplStatus)
Note: Function name 'MyErrorHandler' can be modified.
C# Syntax
[GlobalEventsAttribute("Replication_OnError", "Define a general event for the event Replication_OnError")]
public static void MyErrorHandler(string sReplOrGroupName, string sMessage,
bool bWillDisable, enmReplStatus eReplStatus)
Parameters
|
Name |
Type |
Description |
|
sReplOrGroupName |
String |
Read only. The name of the replication or group that generated the event. |
|
sMessage |
String |
Read only. The error message/exception stack.
|
|
bWillDisable |
Boolean |
Read only. True if the error will disable the replication.
|
|
eReplStatus |
enmReplStatus |
Read only. Specifies the replication status when the event is called using the enmReplStatus enumerator. Possible values for the enumerator are:
|
VB.NET Example
<GlobalEventsAttribute("Replication_OnError", "General event for the event OnError")> _
Public Shared Sub MyGlobalEvent (ByVal sReplicationName As String, ByVal sMessage As String,
ByVal bWillBeDisabled As Boolean, ByVal eReplStatus As enmReplStatus)
Dim s As String
s = DateTime.Now.ToString() + Environment.NewLine + Environment.NewLine
s = s + "Error in replication '" + sReplicationName + "'"
+ Environment.NewLine + Environment.NewLine
s = s + "Replication Status: " + eReplStatus.ToString() + Environment.NewLine
+ Environment.NewLine
s = s + sMessage + Environment.NewLine + Environment.NewLine
If bWillBeDisabled Then
s = s + "The replication will be disabled." + Environment.NewLine + Environment.NewLine
End If
s = s + "-----------------------------------------------------------------" + Environment.NewLine
s = s + " This is an automatic message generated by the Syniti DR script" + Environment.NewLine
s = s + "-----------------------------------------------------------------" + Environment.NewLine
IGlobalScript.SendMail ("Syniti DR Error", s)
End Sub
C# Example
/// <param name="sReplicationName"></param> /// <param name="sMessage"></param> /// <param name="bWillBeDisabled"></param> /// <param name="eReplStatus"></param>
[GlobalEventsAttribute("Replication_OnError", "General event for the event OnError")]
public static void MyGlobalEvent(String sReplicationName, String sMessage, Boolean bWillBeDisabled,
enmReplStatus eReplStatus)
{
String s = null;
s = DateTime.Now.ToString() + Environment.NewLine + Environment.NewLine;
s = s + "Error in replication '" + sReplicationName + "'"
+ Environment.NewLine + Environment.NewLine;
s = s + "Replication Status: " + eReplStatus.ToString() + Environment.NewLine
+ Environment.NewLine;
s = s + sMessage + Environment.NewLine + Environment.NewLine;
if (bWillBeDisabled)
{
s = s + "The replication will be disabled." + Environment.NewLine + Environment.NewLine;
}
s = s + "---------------------------------------------" + Environment.NewLine;
s = s + " This automatic message is generated by the Syniti DR script" + Environment.NewLine;
s = s + "---------------------------------------------" + Environment.NewLine;
IGlobalScript.SendMail("Syniti DR Error", s);
}
ReplicationManager_onStart
This event occurs when the Replication Agent is started. It can be used to add a notification message to the Syniti DR log, or to send email to an administrator. To write a handler for the event, position the cursor inside the class header "Public Class GlobalEvents : Inherits IGlobalEvents", then define the handler using the example below as guideline.
The GlobalEventsAttribute first parameter must indicate the event name "ReplicationManager_OnStart".
VB.NET Syntax
<GlobalEventsAttribute("ReplicationManager_OnStart", "Standard event for the event OnStart")> _
Public Shared Sub OnStart ()
C# Syntax
[GlobalEventsAttribute("ReplicationManager_OnStart", "Standard event for the event OnStart")]
public static void OnStart()
Parameters
None.
VB.NET Example
<GlobalEventsAttribute("ReplicationManager_OnStart", "Standard event for the event OnStart")> _
Public Shared Sub OnStart ()
Dim s As String
s = s + "-- Message from Syniti DR - START"
s = s + "-----------------------------------------------------------------"
+ Environment.NewLine
s = s + "- This is an automatic message generated by the Syniti DR
script -" + Environment.NewLine
s = s + "-----------------------------------------------------------------"
+ Environment.NewLine IGlobalScript.SendMail
("Replication Manager Message", s)
End Sub
C# Example
[GlobalEventsAttribute("ReplicationManager_OnStart", "Standard event for the event OnStart")]
public static void OnStart()
{
String s = null;
s = s + "-- Message from Syniti DR - START";
s = s + "-------------------------------------------------------" + Environment.NewLine;
s = s + "- This is an automatic message generated by the Syniti DR script -" + Environment.NewLine;
s = s + "-------------------------------------------------------" + Environment.NewLine;
IGlobalScript.SendMail("Replication Manager Message", s);
}
ReplicationManager_onStop
This event occurs when the Data Replicator is started. It can be used to add a notification message to the Syniti DR log, or to send email to an administrator. To write a handler for the event, position the cursor inside the class header "Public Class GlobalEvents : Inherits IGlobalEvents", then define the handler using the example below as a guideline.
The GlobalEventsAttribute first parameter must indicate the event name "ReplicationManager_OnStop".
VB.NET Syntax
<GlobalEventsAttribute("ReplicationManager_OnStop", "Standard event for the event OnStop")> _
Public Shared Sub OnStop ()
C# Syntax
[GlobalEventsAttribute("ReplicationManager_OnStop", "Standard event for the event OnStop")]
public static void OnStop()
Parameters
None.
VB.NET Example
<GlobalEventsAttribute("ReplicationManager_OnStop", "Standard event for the event OnStop")>
Public Shared Sub OnStop ()
Dim s As String
s = s + "-- Message from Syniti DR - STOP"
s = s + "---------------------------------------------------------" + Environment.NewLine
s = s + "This is an automatic message generated by the Syniti DR script -" + Environment.NewLine
s = s + "--------------------------------------------------------"
+ Environment.NewLine
IGlobalScript.SendMail ("Replication Manager Message", s)
End Sub
C# Example
[GlobalEventsAttribute("ReplicationManager_OnStop", "Standard event for the event OnStop")]
public static void OnStop()
{
String s = null;
s = s + "-- Message from Syniti DR - STOP";
s = s + "--------------------------------------------------------" + Environment.NewLine;
s = s + "- This is an automatic message generated by the Syniti DR script -" + Environment.NewLine;
s = s + "---------------------------------------------------------" + Environment.NewLine;
IGlobalScript.SendMail("Replication Manager Message", s);
}
