sp_hook_dbmlsync_all_error

Use this stored procedure to process dbmlsync error messages of all types. For example, you can implement the sp_hook_dbmlsync_all_error hook to log errors or perform a specific action when a specific error occurs.

Rows in #hook_dict table

Name

Value

Description

publication_n (in)

publication

The publications being synchronized, where n is an integer. There is one publication_n entry for each publication being uploaded. The numbering of n starts at zero.

MobiLink user (in)

MobiLink user name

The MobiLink user for which you are synchronizing.

script version (in)

script version name

The MobiLink script version that is used for the synchronization.

error message (in) error message text This is the same text that is displayed in the dbmlsync log.
error id (in) integer An ID that uniquely identifies the message. Use this row to identify the error message, as the error message text may change.
error hook user state (in|out) integer

This value can be set by the hook to pass state information to future calls to the sp_hook_dbmlsync_all_error, sp_hook_dbmlsync_communication_error, sp_hook_dbmlsync_misc_error, sp_hook_dbmlsync_sql_error, or sp_hook_dbmlsync_end hooks. The first time one of these hooks is called, the value of the row is 0. If the hook changes the value of the row, the new value is used in the next hook call.

When you use this hook to pass state information to the sp_hook_dbmlsync_end hook, you can cause the sp_hook_dbmlsync_end hook to perform actions such as retrying the synchronization.

Remarks

Each time a dbmlsync error message is generated, the following hooks are called:

  • First, depending on the type of error, one of the following hooks is called: sp_hook_dbmlsync_communication_error, sp_hook_dbmlsync_misc_error, or sp_hook_dbmlsync_sql_error. These hooks contain information specific to the type of error; for example, sqlcode and sqlstate are provided for SQL errors.
  • Next, the sp_hook_dbmlsync_all_error is called. This hook is useful for logging all errors that occurred.

If an error occurs during startup before a synchronization has been initiated, the #hook_dict entries for MobiLink user and Script version are set to an empty string, and no publication_n rows are set in the #hook_dict table.

This procedure executes on a separate connection to ensure that operations it performs are not lost if a rollback is performed on the synchronization connection. If dbmlsync cannot establish a separate connection, the procedure is not called.

By default on Windows Mobile devices, synchronization tables are locked in exclusive mode, which means that this hook cannot successfully execute if it requires access to any of the synchronization tables. It also cannot execute if it needs to access synchronization tables and you set the dbmlsync extended option LockTables to EXCLUSIVE. See LockTables (lt) extended option.

Actions of this procedure are committed immediately after the hook completes.

See also
Example

Assume you use the following table to log errors in the remote database.

CREATE TABLE error_log
(
 pk INTEGER DEFAULT AUTOINCREMENT PRIMARY KEY,
 err_id INTEGER,
 err_msg VARCHAR(10240),
);

The following example sets up sp_hook_dbmlsync_all_error to log errors.

CREATE PROCEDURE sp_hook_dbmlsync_all_error()
BEGIN
 DECLARE msg VARCHAR(10240);
 DECLARE id INTEGER;

 // get the error message text
 SELECT value INTO msg
  FROM #hook_dict
  WHERE name ='error message';

 // get the error id
 SELECT value INTO id
  FROM #hook_dict
  WHERE name = 'error id';

 // log the error information
 INSERT INTO error_log(err_msg, err_id)
  VALUES (msg, id);
END;

To see possible error id values, test run dbmlsync. For example, if dbmlsync returns the error "Unable to connect to MobiLink server", sp_hook_dbmlsync_all_error inserts the following row in error_log.

1,14173,
 'Unable to connect to MobiLink server'

Now, you can associate the error "Unable to connect to MobiLink server" with the error id 14173.

The following example sets up hooks to retry the synchronization whenever error 14173 occurs.

CREATE PROCEDURE sp_hook_dbmlsync_all_error()
BEGIN
 IF EXISTS( SELECT value FROM #hook_dict 
    WHERE name = 'error id' AND value = '14173' )
 THEN
    UPDATE #hook_dict SET value = '1' 
       WHERE name = 'error hook user state';
   END IF;
END;

CREATE PROCEDURE sp_hook_dbmlsync_end()
BEGIN
 IF EXISTS( SELECT value FROM #hook_dict 
    WHERE name='error hook user state' AND value='1')
 THEN
    UPDATE #hook_dict SET value = 'sync' 
       WHERE name='restart';
   END IF;
END;

See sp_hook_dbmlsync_end.