Filter プロパティ

  • [アーティクル]

Recordset 内のデータのフィルターを示します。

設定と戻り値

次の項目のいずれかを含む Variant 値を設定するか、返します。

  • 条件文字列:AND または OR 演算子で連結された、1 つ以上の個々の句で構成される文字列。

  • ブックマークの配列:Recordset オブジェクト内のレコードを指す一意のブックマーク値の配列。

  • FilterGroupEnum 値。

注釈

Filter プロパティは、Recordset オブジェクト内のレコードを選別して除外するために使用されます。 フィルター処理された Recordset は、現在のカーソルになります。 AbsolutePosition プロパティ (ADO)、AbsolutePage プロパティ (ADO)、RecordCount プロパティ (ADO)、PageCount プロパティ (ADO) など、現在のカーソルに基づいて値を返す他のプロパティが影響を受けます。 Filter プロパティを特定の新しい値に設定すると、現在のレコードが新しい値を満たす最初のレコードに移動します。

条件文字列は、"FieldName 演算子値" 形式の句 (たとえば "LastName = 'Smith'") で構成されます。 複合句は、AND (たとえば "LastName = 'Smith' AND FirstName = 'John'") と OR (たとえば "LastName = 'Smith' OR LastName = 'Jones'") を使用して個々の句を連結することで作成できます。 条件文字列については次のガイドラインに従ってください。

  • FieldName は、Recordsetの有効なフィールド名である必要があります。 フィールド名にスペースが含まれる場合は、名前を角かっこで囲む必要があります。

  • 演算子は、<、>、<=、>=、<>、=、LIKE のいずれかである必要があります。

  • 値は、フィールド値と比較する値です (たとえば、'Smith'、#8/24/95#、12.345、$50.00)。 文字列には単一引用符を使用し、日付にはシャープ記号 (#) を使用します。 数値には、小数点、ドル記号、科学的表記を使用できます。 演算子が LIKE の場合、値にはワイルドカード文字を使用できます。 アスタリスク (*) とパーセント記号 (%) のワイルドカード文字のみを使用でき、それらを文字列の最後の文字にする必要があります。 値を null にすることはできません。

注意

フィルター値に単一引用符 (') を含めるには、2 つの単一引用符を使用して 1 つを表します。 たとえば、O'Malley でフィルター処理するには、条件文字列を "col1 = 'O''Malley'" にする必要があります。 フィルター値の先頭と末尾の両方に単一引用符を含めるには、文字列をシャープ記号 (#) で囲みます。 たとえば、'1' でフィルター処理するには、条件文字列を "col1 = #'1'#" にする必要があります。

  • AND と OR の間に優先順位はありません。 句はかっこ内でグループ化できます。 ただし、次のコード スニペットに示すように、OR で結合された句をグループ化して、AND を使用して別の句にグループを結合することはできません。
    (LastName = 'Smith' OR LastName = 'Jones') AND FirstName = 'John'

  • 代わりに、このフィルターを次のように構築します。
    (LastName = 'Smith' AND FirstName = 'John') OR (LastName = 'Jones' AND FirstName = 'John')

  • LIKE 句では、パターンの先頭と末尾にワイルドカード文字を使用できます。 たとえば、LastName Like '*mit*' を使用できます。 または、LIKE では、パターンの末尾にのみワイルドカード文字を使用できます。 たとえば、「 LastName Like 'Smit*' 」のように入力します。

フィルター定数を使用すると、たとえば、最後の UpdateBatch メソッド呼び出し中に影響を受けたレコードのみを表示できるようにすることで、バッチ更新モード中の個々のレコードの競合を簡単に解決できます。

基になるデータとの競合が原因で、Filter プロパティ自体の設定に失敗する場合があります。 たとえば、レコードが他のユーザーによって既に削除されている場合、この失敗が発生する可能性があります。 このような場合、プロバイダーは Errors コレクション (ADO) に警告を返しますが、プログラムの実行は停止されません。 実行時エラーは、要求したすべてのレコードで競合が発生した場合にのみ発生します。 競合が発生したレコードを見つけるには、Status プロパティ (ADO Recordset) を使用します。

Filter プロパティを長さ 0 の文字列 ("") に設定すると、adFilterNone 定数を使用した場合と同じ結果が得られます。

Filter プロパティを設定すると、Recordset 内のレコードのフィルター処理されたサブセット内で最初のレコードに現在のレコードの位置が移動します。 同様に、Filter プロパティをクリアすると、現在のレコードの位置は、Recordset 内で最初のレコードに移動します。

Recordset は、sql_variant 型などのバリアント型のフィールドに基づいてフィルター処理されるとします。 条件文字列で使用されているフィールドとフィルター値のサブタイプが一致しない場合、エラー (DISP_E_TYPEMISMATCH または 80020005) が発生します。 たとえば、次のように想定します。

  • Recordset オブジェクト (rs) には、sql_variant 型の列 (C) が含まれています。
  • この列のフィールドには、I4 型の値 1 が割り当てられています。 条件文字列は、フィールドに対して rs.Filter = "C='A'" に設定されています。

この構成では、実行時にエラーが発生します。 しかし、同じフィールドに rs.Filter = "C=2" が適用された場合、エラーは発生しません。 さらに、フィールドは現在のレコード セットから除外されます。

Filter プロパティで使用する配列を作成できるブックマーク値については、「Bookmark プロパティ (ADO)」を参照してください。

条件文字列形式のフィルターのみが、保持された Recordset の内容に影響します。 条件文字列の一例は、OrderDate > '12/31/1999' です。 ブックマークの配列または FilterGroupEnum の値を使用して作成されたフィルターは、保持された Recordset の内容に影響しません。 これらの規則は、クライアント側またはサーバー側カーソルで作成された Recordset に適用されます。

注意

バッチ更新モードでフィルター処理および変更された Recordset に adFilterPendingRecords フラグを適用すると、フィルター処理が単一キーテーブルのキー フィールドに基づく場合、キー フィールド値が変更されると、結果の Recordset は空になります。 次のいずれかのステートメントが真の場合、結果の Recordset は空ではありません。

  • フィルター処理が、単一キー テーブルの非キー フィールドに基づいて行われた。

  • フィルター処理が、複数キー テーブルの任意のフィールドに基づいて行われた。

  • 変更が、単一キー テーブルの非キー フィールドに基づいて行われた。

  • 変更が、複数キー テーブルの任意のフィールドに基づいて行われた。

次の表は、フィルター処理と変更のさまざまな組み合わせにおける adFilterPendingRecords の効果をまとめたものです。 左側の列は、可能な変更を示します。 変更は、非キー フィールド、単一キー テーブルのキー フィールド、または複数キー テーブルのキー フィールドのいずれかに対して行うことができます。 一番上の行は、フィルター条件を示します。 フィルター処理は、非キー フィールド、単一キー テーブルのキー フィールド、または複数キー テーブルのキー フィールドのいずれかに基づいて行うことができます。 交差するセルは、結果を示します。 + (プラス) 記号は、adFilterPendingRecords を適用すると、空ではない Recordset が得られることを意味します。 - (マイナス) 記号は、空の Recordset が得られることを意味します。

組み合わせ 非キー 単一キー 複数キー
非キー + + +
単一キー + - 該当なし
複数キー + 該当なし +

適用対象

Recordset オブジェクト (ADO)

参照

Filter プロパティと RecordCount プロパティの使用例 (VB)Filter プロパティと RecordCount プロパティの使用例 (VC++)Clear メソッド (ADO)Optimize プロパティ - 動的 (ADO)