適用先: Access 2013、Office 2013
すべてのイベント ハンドラーには、イベント ハンドラーを制御するステータス パラメーターがあります。 Complete イベントの場合、このパラメーターは、そのイベントを生成した操作の成功または失敗をも示します。 また、ほとんどの Complete イベントには、その操作の実行に使用された ADO オブジェクトを参照する 1 つまたは複数のオブジェクト パラメーターに加えて、発生した可能性のあるエラーについての情報が設定されるエラー パラメーターもあります。 たとえば、ExecuteComplete イベントには、このイベントに関連する Command オブジェクト、 Recordset オブジェクト、および Connection オブジェクト用のオブジェクト パラメーターが含まれています。 次の Microsoft Visual Basic の例にある、pCommand オブジェクト、pRecordset オブジェクトと pConnection オブジェクトはそれぞれ、 Execute メソッドで使用される Command オブジェクト、 Recordset オブジェクト、および Connection オブジェクトを表しています。
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 など) が呼び出されているか、または再クエリの結果として発生する可能性があります。
ステータス パラメーター
イベント ハンドラー ルーチンが呼び出されると、"ステータス" パラメーターが次の値のいずれか 1 つに設定されます。
値 |
説明 |
|---|---|
adStatusOK |
Will イベントと Complete イベントの両方に渡されます。 イベントを発生させた操作が正常に完了したことを示します。 |
adStatusErrorsOccurred |
Complete イベントにのみ渡されます。 イベントを発生した操作が失敗したこと、または Will イベントがその操作をキャンセルしたことを示します。 詳細については、「エラー パラメーター」を参照してください。 |
adStatusCantDeny |
Will イベントにのみ渡されます。 Will イベントで操作をキャンセルできないことを示します。 この操作は実行する必要があります。 |
Will イベントで操作を続行する必要があると判断した場合は、 Status パラメーターは変更しないでください。 ただし、受信状態パラメーターが adStatusCantDeny に設定されていない限り、 Status を adStatusCancel に変更することで、保留中の操作を取り消すことができます。 これを行うと、操作に関連付けられている Complete イベントの Status パラメーターが adStatusErrorsOccurred に設定されます。 The Error object passed to the Complete event will contain the value adErrOperationCancelled.
イベントを処理しない場合は、[ 状態] を adStatusUnwantedEvent に設定すると、アプリケーションはそのイベントの通知を受け取らなくなります。 Remember, however, that some events can be raised for more than one reason. In that case, you must specify adStatusUnwantedEvent for each possible reason. たとえば、保留中の RecordChange イベントの通知の受信を停止するには、status パラメーターを adRsnAddNew、adRsnDelete、adRsnDelete、adRsnUpdate、adRsnUndoAddNew、adRsnUndoDelete、adRsnFirstChange に設定する必要があります。
値 |
説明 |
|---|---|
adStatusUnwantedEvent |
イベント ハンドラーがこれ以降の通知を受け入れないようにします。 |
adStatusCancel |
これから実行する操作のキャンセルを要求します。 |
エラー パラメーター
Error パラメーターは、ADO Error オブジェクトへの参照です。 Status パラメーターが adStatusErrorsOccurred に設定されている場合、Error オブジェクトには操作が失敗した理由の詳細が含まれます。 Complete イベントに関連付けられている Will イベントが Status パラメーターを adStatusCancel に設定して操作を取り消した場合、エラー オブジェクトは常に adErrOperationCancelled に設定されます。
オブジェクト パラメーター
各イベントでは、操作に関係するオブジェクトを表す 1 つまたは複数のオブジェクトを受け取ります。 たとえば、ExecuteComplete イベントでは、Command オブジェクト、Recordset オブジェクト、および Connection オブジェクトを受け取ります。
理由パラメーター
Reason パラメーター adReason は、イベントが発生した理由に関する追加情報を提供します。 adReason パラメーターを持つイベントは、同じ操作であっても、別の理由で毎回複数回呼び出される場合があります。 For example, the WillChangeRecord event handler is called for operations that are about to do or undo the insertion, deletion, or modification of a record. 特定の理由でイベントが発生したときにのみイベントを処理する場合は、 adReason パラメーターを使用して、関心のないイベントを除外できます。 For example, if you wanted to process record-change events only when they occur because a record was added, you can do something like this:
' 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 回設定するだけで済みます。