MobiLink Synchronization Reference
  Synchronization Events

handle_error connection event

Function 

Executed whenever the MobiLink synchronization server encounters a SQL error.

Parameters 

In the following table, the description provides the SQL data type. If you are writing your script in Java or .NET, you should use the appropriate corresponding data type. See SQL-Java data types and SQL-.NET data types.

Event parameters are optional only if no subsequent parameters are specified. For example, you must use parameter 1 if you want to use parameter 2.

Default action 

When no handle_error script is defined or this script causes an error, the default action code is 3000: rollback the current transaction and cancel the current synchronization.

Description 

The MobiLink synchronization server sends in the current action_code. Initially, this is set to 3000 for each set of errors caused by a single SQL operation. Usually, there is only one error per SQL operation, but there may be more. This handle_error script is called once per error in the set. The action code passed into the first error is 3000. Subsequent calls are passed in the action code returned by the previous call. MobiLink will use the numerically highest value returned from multiple calls.

You can modify the action code in the script, and return a value instructing MobiLink how to proceed. The action code parameter takes one of the following values:

• 1000    Skip the current row and continue processing.

• 3000    Rollback the current transaction and cancel the current synchronization. This is the default action code, and is used when no handle_error script is defined or this script causes an error.

• 4000    Rollback the current transaction, cancel the synchronization, and shut down the MobiLink synchronization server.

SQL scripts for the handle_error event must be implemented as stored procedures.

The MobiLink synchronization server executes this script whenever it encounters an error during the synchronization process. The error codes and message allow you to identify the nature of the error. If the error happened as part of synchronization, the user name is supplied. Otherwise, this value is NULL.

If the error happened while manipulating a particular table, the table name is supplied. Otherwise, this value is NULL. The table name is the name of a table in the client application. This name may or may not have a direct counterpart in the consolidated database, depending upon the design of the synchronization system.

The action code tells the MobiLink synchronization server what to do next. Before it calls this script, the MobiLink synchronization server sets the action code to a default value, which depends upon the severity of the error. Your script may modify this value. Your script must return or set an action code.

You can return a value from the handle_error script in two ways.

• Pass the action parameter to an OUTPUT parameter of a procedure:

  CALL my_handle_error( ?, ?, ?, ?, ? )

• Set the action code via a procedure or function return value:

  ? = CALL my_handle_error( ?, ?, ?, ? )

  Most DBMSs use the RETURN statement to set the return value from a procedure or function.

The CustDB sample application contains error handlers for various database-management systems.

See also 

report_error connection event

report_odbc_error connection event

handle_odbc_error connection event

SQL example 

The following example works with an Adaptive Server Anywhere consolidated database. It allows your application to ignore redundant inserts.

CREATE PROCEDURE ULHandleError(
   INOUT action integer,
   IN error_code integer,
   IN error_message varchar(1000),
   IN user_name varchar(128),
   IN table_name varchar(128) )
BEGIN
  -- -196 is SQLE_INDEX_NOT_UNIQUE
  -- -194 is SQLE_INVALID_FOREIGN_KEY

  if error_code = -196 or error_code = -194 then
      -- ignore the error and keep going
      SET action = 1000;
  else
      -- abort the synchronization
      SET action = 3000;
  end if;
END

Java example 

The following stored procedure call registers a Java method called handleError as the script for the handle_error connection event when synchronizing the script version ver1. This syntax is for Adaptive Server Anywhere consolidated databases.

call ml_add_java_connection_script(
    'ver1',
    'handle_error',
    'ExamplePackage.ExampleClass.handleError' )

Following is the sample Java method handleError. It processes an error based on the data that is passed in. It also determines the resulting error code.

public String handleError(
  ianywhere.ml.script.InOutInteger actionCode,
  int errorCode,
  String errorMessage,
  String    user,
  String  table )
{  int new_ac;
   if( user == null )
   {  new_ac = handleNonSyncError( errorCode,
      errorMessage ); }
   else if( table == null )

   {  new_ac = handleConnectionError( errorCode,
      errorMessage, user ); }
   else
   {  new_ac = handleTableError( errorCode,
      errorMessage, user, table ); }
   // keep the most serious action code
   if( actionCode.getValue() < new_ac )
   {  actionCode.setValue( new_ac ); }
   return( null ); }