イベント パラメーター

  • [アーティクル]

すべてのイベント ハンドラーには、イベント ハンドラーを制御する状態パラメーターがあります。 Complete イベントの場合、このパラメーターは、イベントを生成した操作の成功または失敗を示すためにも使用されます。 また、ほとんどの Complete イベントには、発生した可能性のあるエラーに関する情報を提供するエラー パラメーターと、操作の実行に使用される ADO オブジェクトを参照する 1 つ以上のオブジェクト パラメーターもあります。 たとえば、ExecuteComplete イベントには、イベントに関連付けられた Command、Recordset、Connection オブジェクトのオブジェクト パラメーターが含まれます。 次の Visual Basic の例では、Execute メソッドで使用される Command、Recordset、Connection オブジェクトを表す pCommand、pRecordset、pConnection オブジェクトを確認できます。

Private Sub connEvent_ExecuteComplete(ByVal RecordsAffected As Long, _  
     ByVal pError As ADODB.Error, _  
     adStatus As ADODB.EventStatusEnum, _  
     ByVal pCommand As ADODB.Command, _  
     ByVal pRecordset As ADODB.Recordset, _  
     ByVal pConnection As ADODB.Connection)

Error オブジェクトを除き、同じパラメーターが Will イベントに渡されます。 これにより、保留中の操作で使用される各オブジェクトを調べ、操作の完了を許可するかどうかを判断できます。

一部のイベント ハンドラーには Reason パラメーターがあり、イベントが発生した理由に関する追加情報を提供します。 たとえば、WillMove および MoveComplete イベントは、いずれかのナビゲーション メソッド (MoveNext、MovePrevious など) が呼び出されているか、または再クエリの結果として発生する可能性があります。

Status パラメーター

イベント ハンドラー ルーチンが呼び出されると、 Status パラメーターは次のいずれかの値に設定されます。

Value 説明
adStatusOK Will および Complete イベントの両方に渡されます。 この値は、イベントの原因となった操作が正常に完了したことを意味します。
adStatusErrorsOccurred Complete イベントにのみ渡されます。 この値は、イベントの原因となった操作が失敗したか、Will イベントによって操作が取り消されたことを意味します。 詳細については、Error パラメーターを確認してください。
adStatusCantDeny Will イベントにのみ渡されます。 この値は、Will イベントによって操作を取り消すことができないことを意味します。 実行する必要があります。

Will イベントで操作を続行する必要があると判断した場合は、Status パラメーターを変更しないでおきます。 ただし、受信状態パラメーターが adStatusCantDeny に設定されていない限り、Status を adStatusCancel に変更することで、保留中の操作を取り消すことができます。 これを行うと、操作に関連付けられている Complete イベントの Status パラメーターが adStatusErrorsOccurred に設定されます。 Complete イベントに渡される Error オブジェクトには、adErrOperationCancelled という値が含まれます。

イベントを処理する必要がなくなった場合は、Status を adStatusUnwantedEvent に設定すると、アプリケーションはそのイベントの通知を受け取らなくなります。 ただし、一部のイベントは複数の理由で発生する可能性があることに注意してください。 その場合は、考えられる理由ごとに adStatusUnwantedEvent を指定する必要があります。 たとえば、保留中の RecordChange イベントの通知の受信を停止するには、adRsnAddNew、adRsnDelete、adRsnUpdate、adRsnUndoUpdate、adRsnUndoAddNew、adRsnUndoDelete、adRsnFirstChange が発生したときに Status パラメーターを adStatusUnwantedEvent に設定する必要があります。

Value 説明
adStatusUnwantedEvent このイベント ハンドラーがそれ以上の通知を受け取らないことを要求します。
adStatusCancel 発生しようとしている操作の取り消しを要求します。

Error パラメーター

Error パラメーターは、ADO Error オブジェクトへの参照です。 Status パラメーターが adStatusErrorsOccurred に設定されている場合、Error オブジェクトには操作が失敗した理由の詳細が含まれます。 Complete イベントに関連付けられている Will イベントによって Status パラメーターが adStatusCancel に設定されて、操作が取り消された場合、エラー オブジェクトは常に adErrOperationCancelled に設定されます。

Object パラメーター

各イベントは、操作に関係するオブジェクトを表す 1 つ以上のオブジェクトを受け取ります。 たとえば、ExecuteComplete イベントは、Command オブジェクト、Recordset オブジェクト、Connection オブジェクトを受け取ります。

Reason パラメーター

Reason パラメーターの adReason は、イベントが発生した理由に関する追加情報を提供します。 adReason パラメーターを持つイベントは、同じ操作であっても、毎回異なる理由で複数回呼び出される場合があります。 たとえば、WillChangeRecord イベント ハンドラーは、レコードの挿入、削除、変更を実行または元に戻す操作に対して呼び出されます。 特定の理由でイベントが発生した場合にのみイベントを処理する場合は、adReason パラメーターを使用して、関心のないイベントを除外できます。 たとえば、レコードが追加されたために発生した場合にのみレコード変更イベントを処理する場合は、次のように使用できます。

' BeginEventExampleVB01  
Private Sub rsTest_WillChangeRecord(ByVal adReason As ADODB.EventReasonEnum, ByVal cRecords As Long, adStatus As ADODB.EventStatusEnum, ByVal pRecordset As ADODB.Recordset)  
   If adReason = adRsnAddNew Then  
       ' Process event  
       '...  
   Else  
       ' Cancel event notification for all  
       ' other possible adReason values.  
       adStatus = adStatusUnwantedEvent  
   End If  
End Sub  
' EndEventExampleVB01

この場合、他の理由ごとに通知が発生する可能性があります。 ただし、これは理由ごとに 1 回だけ発生します。 通知が理由ごとに 1 回発生した後は、新しいレコードの追加についてのみ通知を受け取ります。

これに対し、adReason パラメーターのないイベント ハンドラーでイベント通知の受信を停止するように要求するには、adStatus を adStatusUnwantedEvent に 1 回だけ設定する必要があります。

参照

ADO イベント ハンドラーの概要
言語別の ADO イベントのインスタンス化
複数のイベント ハンドラーの連携方法
イベントの種類