Filter, propriété

  • Article

Indique un filtre pour les données dans un Recordset.

Paramètres et valeurs de retour

Définit ou retourne une valeur Variant , qui peut contenir l’un des éléments suivants :

  • Chaîne de critères : Chaîne composée d’une ou plusieurs clauses individuelles concaténées avec des opérateurs AND ou OR .

  • Tableau de signets : Tableau de valeurs de signet uniques qui pointent vers des enregistrements dans l’objet Recordset .

  • Valeur FilterGroupEnum .

Notes

Utilisez la propriété Filter pour filtrer sélectivement les enregistrements dans un objet Recordset . Le Recordset filtré devient le curseur actuel. D’autres propriétés qui retournent des valeurs basées sur le curseur actuel sont affectées, telles que AbsolutePosition, Property (ADO), AbsolutePage, RecordCount Property (ADO) et PageCount Property (ADO). La définition de la propriété Filter sur une nouvelle valeur spécifique déplace l’enregistrement actif vers le premier enregistrement qui satisfait à la nouvelle valeur.

La chaîne de critères est constituée de clauses sous forme FieldName-Operator-Value (par exemple). "LastName = 'Smith'" Vous pouvez créer des clauses composées en concaténant des clauses individuelles avec AND (par exemple, "LastName = 'Smith' AND FirstName = 'John'") ou OR (par exemple). "LastName = 'Smith' OR LastName = 'Jones'" Pour les chaînes de critères, utilisez les instructions suivantes :

  • FieldName doit être un nom de champ valide à partir de l’objet Recordset. Si le nom de champ contient des espaces, vous devez le mettre entre crochets.

  • L’opérateur doit être l’un de ceux-ci :<, >, <=, >=, <>, =, ou LIKE.

  • La valeur est la valeur avec laquelle vous allez comparer les valeurs de champ (par exemple, « Smith », #8/24/95#, 12,345 ou $50.00). Utilisez des guillemets uniques avec des chaînes et des signes de livre (#) avec des dates. Pour les nombres, vous pouvez utiliser des points décimaux, des signes dollar et une notation scientifique. Si l’opérateur est LIKE, la valeur peut utiliser des caractères génériques. Seuls les astérisque (*) et le signe de pourcentage (%) sont autorisés, et ils doivent être le dernier caractère de la chaîne. Value cannot be null.

Notes

Pour inclure des guillemets uniques (') dans la valeur de filtre, utilisez deux guillemets simples pour en représenter un. Par exemple, pour filtrer sur O’Malley, la chaîne de critères doit être "col1 = 'O''Malley'". Pour inclure des guillemets simples au début et à la fin de la valeur de filtre, placez la chaîne avec des signes de livre (#). Par exemple, pour filtrer sur « 1 », la chaîne de critères doit être "col1 = #'1'#".

  • Il n’existe aucune priorité entre AND et OR. Les clauses peuvent être regroupées entre parenthèses. Toutefois, vous ne pouvez pas regrouper les clauses jointes par une OR, puis joindre le groupe à une autre clause avec un AND, comme dans l’extrait de code suivant :
    (LastName = 'Smith' OR LastName = 'Jones') AND FirstName = 'John'

  • Au lieu de cela, vous allez construire ce filtre comme
    (LastName = 'Smith' AND FirstName = 'John') OR (LastName = 'Jones' AND FirstName = 'John')

  • Dans une clause LIKE , vous pouvez utiliser un caractère générique au début et à la fin du modèle. Par exemple, vous pouvez utiliser LastName Like '*mit*'. Ou avec LIKE , vous pouvez utiliser un caractère générique uniquement à la fin du modèle. Par exemple : LastName Like 'Smit*'.

Les constantes de filtre facilitent la résolution des conflits d’enregistrements individuels lors du mode de mise à jour par lot en vous permettant d’afficher, par exemple, uniquement ces enregistrements affectés lors de l’appel de la méthode UpdateBatch .

La définition de la propriété Filter elle-même peut échouer en raison d’un conflit avec les données sous-jacentes. Par exemple, cette défaillance peut se produire lorsqu’un enregistrement a déjà été supprimé par un autre utilisateur. Dans ce cas, le fournisseur retourne des avertissements à la collection Errors Collection (ADO), mais ne cesse pas l’exécution du programme. Une erreur d’exécution ne se produit que s’il existe des conflits sur tous les enregistrements demandés. Utilisez la propriété Status Property (ADO Recordset) pour localiser les enregistrements en conflit.

La définition de la propriété Filter sur une chaîne de longueur nulle («  ») a le même effet que l’utilisation de la constante adFilterNone .

Chaque fois que la propriété Filter est définie, la position d’enregistrement actuelle se déplace vers le premier enregistrement dans le sous-ensemble filtré d’enregistrements dans Recordset. De même, lorsque la propriété Filter est effacée, la position d’enregistrement actuelle se déplace vers le premier enregistrement dans l’objet Recordset.

Supposons qu’un Recordset soit filtré en fonction d’un champ de type variant, tel que le type sql_variant. Une erreur (DISP_E_TYPEMISMATCH ou 80020005) se produit lorsque les sous-types du champ et des valeurs de filtre utilisées dans la chaîne de critères ne correspondent pas. Par exemple, supposons que :

  • Un objet Recordset (rs) contient une colonne (C) du type sql_variant.
  • Et un champ de cette colonne a été attribué une valeur de 1 du type I4. La chaîne de critères est définie rs.Filter = "C='A'" sur le champ.

Cette configuration génère l’erreur pendant l’exécution. Toutefois, rs.Filter = "C=2" l’application sur le même champ ne produit aucune erreur. Et le champ est filtré sur le jeu d’enregistrements actuel.

Consultez la propriété Bookmark Property (ADO) pour obtenir une explication des valeurs de signet à partir de laquelle vous pouvez créer un tableau à utiliser avec la propriété Filter.

Seuls les filtres sous forme de chaînes de critères affectent le contenu d’un Recordset persistant. Un exemple de chaîne de critère est OrderDate > '12/31/1999'. Les filtres créés avec un tableau de signets ou à l’aide d’une valeur de FilterGroupEnum n’affectent pas le contenu du Recordset persistant. Ces règles s’appliquent aux jeux d’enregistrements créés avec des curseurs côté client ou côté serveur.

Notes

Lorsque vous appliquez l’indicateur adFilterPendingRecords à un Recordset filtré et modifié en mode de mise à jour par lots, le Recordset résultant est vide si le filtrage était basé sur le champ clé d’une table à clé unique et que la modification a été effectuée sur les valeurs de champ clé. Le Recordset résultant n’est pas vide si l’une des instructions suivantes est vraie :

  • Le filtrage était basé sur des champs non clés dans une table à clé unique.

  • Le filtrage était basé sur tous les champs d’une table à plusieurs clés.

  • Les modifications ont été apportées sur les champs non clés d’une table à clé unique.

  • Les modifications ont été apportées sur tous les champs d’une table à plusieurs clés.

Le tableau suivant récapitule les effets adFilterPendingRecords dans différentes combinaisons de filtrage et de modifications. La colonne gauche affiche les modifications possibles. Les modifications peuvent être apportées sur l’un des champs non clés, sur le champ clé d’une table à clé unique ou sur l’un des champs clés d’une table à plusieurs clés. La ligne supérieure affiche le critère de filtrage. Les modifications peuvent être apportées sur l’un des champs non clés, sur le champ clé d’une table à clé unique ou sur l’un des champs clés d’une table à plusieurs clés. Les cellules croisées affichent les résultats. Un + signe plus signifie que l’application d’adFilterPendingRecords génère un Recordset non vide. Un - signe moins signifie un Recordset vide.

Combinaisons Non clés Clé unique Plusieurs clés
Non clés + + +
Clé unique + - N/A
Plusieurs clés + N/A +

S'applique à

Recordset, objet (ADO)

Voir aussi

Exemple de propriétés Filter et RecordCount (VB) Exemple de propriétés Filter et RecordCount (VC++) Méthode Clear (ADO) Optimisation de la propriété-Dynamique (ADO)