--- title: "Global Script Events" slug: "global-script-events" updated: 2024-03-28T17:11:03Z published: 2024-03-28T17:11:03Z canonical: "skthelp.syniti.com/global-script-events" --- > ## Documentation Index > Fetch the complete documentation index at: https://skthelp.syniti.com/llms.txt > Use this file to discover all available pages before exploring further. # 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](/v1/docs/global-script-events#recordonexecuteerror) and [Replication_OnError](/v1/docs/global-script-events#replicationonerror) 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 Replicate, 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](/v1/docs/managing-reader-and-writer-events-in-a-script), 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 iteration parameters, might allow the operation to succeed a few milliseconds later. Note that the replication event [Record_OnBeforeExecute](/v1/docs/replication-script-events#recordonbeforeexecute) is generated only once, no matter how many times the record operation is retried using this parameter. Also, the replication event [Record_OnAfterExecute](/v1/docs/replication-script-events#recordonafterexecute) is generated once only if the record operation succeeds and not at all if the record operation fails. The [GlobalEventsAttribute](/v1/docs/global-script-events#globaleventsattribute) first parameter must indicate the event name "Record_OnExecuteError". ### VB.NET Syntax ```plaintext 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] > Note > > Function name 'MyErrorHandler' can be modified. ### C# Syntax ```plaintext [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 | [IRecord](/v1/docs/irecord-interface) | 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](/v1/docs/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 error 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 Replicate 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](/v1/docs/replication-script-events#recordonbeforeexecute) is generated only once, no matter how many times the record operation is retried using this parameter. Also, the replication event [Record_OnAfterExecute](/v1/docs/replication-script-events#recordonafterexecute) 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. | | iteration | 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 ```plaintext 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 ```plaintext public class GlobalEvents : IGlobalEvents {  ///      ///  ///  ///  ///  ///  /// [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](/v1/docs/global-script-events#globaleventsattribute) first parameter must indicate the event name "Record_OnMappingError". ### VB.NET Syntax > [!NOTE] > Note > > Function name 'MyErrorHandler' can be modified. ```plaintext 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 ```plaintext [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](/v1/docs/irecord-interface) | 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](/v1/docs/irecord-interface). | | recTarget | [IRecord](/v1/docs/irecord-interface) | 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](/v1/docs/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 Replicate 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](/v1/docs/replication-script-events#recordonbeforeexecute) is generated only once, no matter how many times the record operation is retried using this parameter. Also the replication event [Record_OnAfterExecute](/v1/docs/replication-script-events#recordonafterexecute) 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 ```plaintext 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 ```plaintext public class GlobalEvents : IGlobalEvents {  ///      ///  ///  ///  ///  ///  /// [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](/v1/docs/global-script-events#globaleventsattribute) first parameter must indicate the event name "Replication_OnError". ### VB.NET Syntax ```plaintext    Public Shared Sub MyErrorHandler (ByVal sReplOrGroupName As String, ByVal sMessage As String,                                    ByVal bWillDisable As Boolean, ByVal eReplStatus As enmReplStatus) ``` > [!NOTE] > Note > > Function name 'MyErrorHandler' can be modified. ### C# Syntax ```plaintext  [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: - **ErrorAndContinue** An error was generated during the replication (refresh or mirroring interval) but the replication was able to continue. An example is when a transaction fails to delete a target record because the record was not found in the target table. In this case, Syniti Replicate reports the error in the log and continues with the next record. - **Error** An error was generated and the replication stopped executing. The replication will start again at the next interval. An example of this type of error is when a connection to the source or target database is broken. In such cases, Syniti Replicate cannot continue with the replication and goes into recovery mode. - **Success** Not used in this event. When Replication_OnError is called, the replication is always in an error state. | ### VB.NET Example ```plaintext _ 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 Replicate script" + Environment.NewLine   s = s + "-----------------------------------------------------------------" + Environment.NewLine   IGlobalScript.SendMail ("Syniti Replicate Error", s) End Sub ``` ### C# Example ```plaintext /// /// /// /// ``` ```plaintext [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 Replicate script" + Environment.NewLine;  s = s + "---------------------------------------------" + Environment.NewLine;   IGlobalScript.SendMail("Syniti Replicate 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 Replicate 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](/v1/docs/global-script-events#globaleventsattribute) first parameter must indicate the event name "ReplicationManager_OnStart". ### VB.NET Syntax ```plaintext   _ Public Shared Sub OnStart () ``` ### C# Syntax ```plaintext [GlobalEventsAttribute("ReplicationManager_OnStart", "Standard event for the event OnStart")] public static void OnStart() ``` ### Parameters None. ### VB.NET Example ```plaintext _ Public Shared Sub OnStart () Dim s As String s = s + "-- Message from Syniti Replicate - START" s = s + "-----------------------------------------------------------------" + Environment.NewLine s = s + "-  This is an automatic message generated by the Syniti Replicate script  -" + Environment.NewLine s = s + "-----------------------------------------------------------------" + Environment.NewLine           IGlobalScript.SendMail ("Replication Manager Message", s) End Sub ``` ### C# Example ```plaintext [GlobalEventsAttribute("ReplicationManager_OnStart",  "Standard event for the event OnStart")] public static void OnStart() {  String s = null; s = s + "-- Message from Syniti Replicate - START"; s = s + "-------------------------------------------------------" + Environment.NewLine; s = s + "-  This is an automatic message generated by the Syniti Replicate 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 Replicate 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](/v1/docs/global-script-events#globaleventsattribute) first parameter must indicate the event name "ReplicationManager_OnStop". ### VB.NET Syntax ```plaintext   _   Public Shared Sub OnStop () ``` ### C# Syntax ```plaintext [GlobalEventsAttribute("ReplicationManager_OnStop", "Standard  event for the event OnStop")] public static void OnStop() ``` ### Parameters None. ### VB.NET Example ```plaintext Public Shared Sub OnStop () Dim s As String s = s + "-- Message from Syniti Replicate - STOP" s = s + "---------------------------------------------------------" + Environment.NewLine s = s + "This is an automatic message generated by the Syniti Replicate script -" + Environment.NewLine s = s + "--------------------------------------------------------" + Environment.NewLine IGlobalScript.SendMail ("Replication Manager Message", s) End Sub ``` ### C# Example ```plaintext [GlobalEventsAttribute("ReplicationManager_OnStop", "Standard event for the event OnStop")] public static void OnStop() {  String s = null;  s = s + "-- Message from Syniti Replicate  - STOP";  s = s + "--------------------------------------------------------" + Environment.NewLine;  s = s + "-  This is an automatic message generated by the Syniti Replicate script  -" + Environment.NewLine;  s = s + "---------------------------------------------------------" + Environment.NewLine;  IGlobalScript.SendMail("Replication Manager Message", s); } ```