handle_error 接続イベント

Mobile Link サーバで SQL エラーが発生したときに実行されます。

パラメータ

次の表の説明では、SQL データ型を示します。Java または .NET でスクリプトを作成する場合、適切なデータ型を使用してください。SQL データ型と Java データ型とSQL データ型と .NET データ型を参照してください。

SQL スクリプトでは、名前または疑問符を使用してイベント・パラメータを指定できますが、スクリプト内に名前と疑問符を混在させることはできません。疑問符を使用する場合、パラメータは以下に示す順に指定する必要があり、後続のパラメータが指定されていない場合のみ省略可能です (たとえば、パラメータ 2 を使用する場合は、パラメータ 1 を使用してください)。名前付きパラメータを使用する場合は、パラメータの任意のサブセットを任意の順に指定できます。

SQL スクリプトのパラメータ名	説明	順序
s.action_code	INTEGER。これは INOUT パラメータです。	1
s.error_code	INTEGER	2
s.error_message	TEXT	3
s.remote_id	VARCHAR(128)。Mobile Link リモート ID。名前付きパラメータを使用している場合のみ、リモート ID を参照できます。	適用不可
s.username	VARCHAR(128)。Mobile Link ユーザ名。	4
s.table	VARCHAR(128)。スクリプトがテーブル・スクリプトでない場合、テーブル名は NULL です。	5

デフォルトのアクション

handle_error スクリプトが定義されない場合、またはこのスクリプトが原因でエラーが発生した場合、デフォルト・アクション・コードは 3000 です。現在のトランザクションをロールバックし、現在の同期をキャンセルします。

備考

Mobile Link サーバは、現在のアクション・コードで送信します。最初は 1 回の SQL 操作によって発生したエラーのセットごとに 3000 が設定されます。通常、エラー数は SQL 操作ごとに 1 つのみですが、複数の場合もあります。この handle_error スクリプトは、セットに含まれるエラーごとに 1 回呼び出されます。最初のエラーに渡されるアクション・コードは 3000 です。以降の呼び出しには、直前の呼び出しから返されたアクション・コードが渡されます。Mobile Link は、複数の呼び出しから返される値のうち最も大きい番号が付いた値を使用します。

スクリプト内でアクション・コードを修正し、Mobile Link に次の処理を指示する値を返すことができます。Mobile Link サーバが次に何を行うかは、アクション・コードに示されます。Mobile Link サーバは、エラーの重大度に応じてアクション・コードにデフォルト値を設定してから、このスクリプトを呼び出します。この値は、スクリプトで変更できます。スクリプトは、必ずアクション・コードを返すか設定するようにします。

アクション・コード・パラメータには、次のいずれかの値を指定します。

1000 現在のローをスキップして、処理を続行します。
3000 現在のトランザクションをロールバックし、現在の同期をキャンセルします。これはデフォルト・アクション・コードで、handle_error スクリプトが定義されない場合、またはこのスクリプトが原因でエラーが発生した場合に使用されます。
4000 現在のトランザクションのロールバック、同期のキャンセル、Mobile Link サーバの停止を行います。

エラーの内容は、エラー・コードとメッセージで識別できます。同期の一部としてエラーが発生した場合は、ユーザ名が指定されます。それ以外の場合、この値は NULL です。

Mobile Link がアップロード・トランザクション中に挿入、更新、または削除スクリプトを処理している間、またはダウンロード・ローをフェッチしている間に ODBC エラーが発生した場合、Mobile Link サーバはこのスクリプトを実行します。別のときに ODBC エラーが発生した場合、Mobile Link サーバは report_error または report_ODBC_error スクリプトを呼び出して、同期をアボートします。

特定のテーブルの操作中にエラーが発生した場合は、テーブル名が指定されます。それ以外の場合、この値は NULL です。テーブル名は、クライアント・アプリケーションでのテーブル名です。この名前に直接対応するものが統合データベース内にあるかどうかは、同期システムの設計によって異なります。

handle_error イベント用の SQL スクリプトは、ストアド・プロシージャとして実装してください。

次のいずれかの方法で、handle_error スクリプトから値を返すことができます。

次のように、プロシージャの OUTPUT パラメータにアクション・パラメータを渡す。

CALL my_handle_error( {ml s.action_code}, {ml s.error_code}, {ml s.error_message}, {ml s.username}, {ml s.table} )

次のように、プロシージャまたは関数の戻り値を介してアクション・コードを設定する。

{ml s.action_code} = CALL my_handle_error( {ml s.error_code}, {ml s.error_message}, {ml s.username}, {ml s.table} )

ほとんどの RDBMS では、RETURN 文を使用してプロシージャまたは関数からの戻り値を設定します。

CustDB サンプル・アプリケーションには、さまざまなデータベース管理環境に対するエラー・ハンドラが含まれています。

参照

SQL の例

次の例は SQL Anywhere 統合データベースで動作します。これによって、アプリケーションは冗長挿入を無視できます。

次の Mobile Link システム・プロシージャ・コールは、ULHandleError ストアド・プロシージャを handle_error イベントに割り当てます。

CALL ml_add_connection_script(
    'ver1',
    'handle_error',
    'CALL ULHandleError(
      {ml s.action_code}, 
      {ml s.error_code}, 
      {ml s.error_message}, 
      {ml s.username}, 
      {ml s.table} )' )

次の SQL 文は ULHandleError ストアド・プロシージャを作成します。

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 の例

次の Mobile Link システム・プロシージャ・コールは、スクリプト・バージョン ver1 を同期するときに、handleError という Java メソッドを handle_error 接続イベント用のスクリプトとして登録します。

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

次に示すのは、サンプルの Java メソッド handleError です。このメソッドは、渡されたデータに基づいてエラーを処理します。また、エラーの結果生じるエラー・コードも判別します。

public String handleError(
  ianywhere.ml.script.InOutInteger actionCode,
  int errorCode,
  String errorMessage,
  String user,
  String table ) {
  int newAC;
  if( user == null ) {
    newAC = handleNonSyncError( errorCode,
    errorMessage ); }
  else if( table == null ) {
    newAC = handleConnectionError( errorCode,
    errorMessage, user ); }
  else {
    newAC = handleTableError( errorCode,
    errorMessage, user, table ); 
  }
  // Keep the most serious action code.
  if( actionCode.getValue() < newAC ) {
    actionCode.setValue( newAC ); 
  }
}

.NET の例

次の Mobile Link システム・プロシージャ・コールは、スクリプト・バージョン ver1 を同期するときに、HandleError という .NET メソッドを handle_error 接続イベント用のスクリプトとして登録します。

CALL ml_add_dnet_connection_script(
  'ver1',
  'handle_error',
  'TestScripts.Test.HandleError' )

次に示すのは、サンプルの .NET メソッド HandleError です。

public string HandleError() (
  ref int 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 < new_ac ) {
    actionCode = new_ac; 
  }
}