Proprietà Filter

  • Articolo

Indica un filtro per i dati in un oggetto Recordset.

Impostazioni e valori restituiti

Imposta o restituisce un valore Variant, che può contenere uno degli elementi seguenti:

  • Stringa di criteri: stringa costituita da una o più clausole singole concatenate con operatori AND oppure OR.

  • Matrice di segnalibri: matrice di valori di segnalibro univoci che puntano al record nell'oggetto Recordset.

  • Valore FilterGroupEnum.

Osservazioni

Usare la proprietà Filter per visualizzare in modo selettivo i record in un oggetto Recordset. L'oggetto Recordset filtrato diventa il cursore corrente. Sono interessate altre proprietà che restituiscono valori in base al cursore corrente, ad esempio AbsolutePosition Property (ADO), AbsolutePage Property (ADO), RecordCount Property (ADO) e PageCount Property (ADO). L'impostazione della proprietà Filter su un valore specifico sposta il record corrente al primo record che soddisfa il nuovo valore.

La stringa di criteri è costituita da clausole nel formato NomeCampo-Operatore-Valore (ad esempio "LastName = 'Smith'"). È possibile creare clausole composte concatenando singole clausole con gli operatori AND (ad esempio "LastName = 'Smith' AND FirstName = 'John'") oppure OR (ad esempio "LastName = 'Smith' OR LastName = 'Jones'"). Per le stringhe di criteri, usare le linee guida seguenti:

  • NomeCampo deve essere un nome di campo valido dell'oggetto Recordset. Se il nome campo include spazi, è necessario racchiuderlo tra parentesi quadre.

  • L'operatore deve essere uno dei seguenti: <, >, <=, >=, <>, = oppure LIKE.

  • Il valore è quello con cui si confronteranno i valori del campo (ad esempio 'Smith', #8/24/95#, 12.345 o $50.00). Usare le virgolette singole con le stringhe e i segni di cancelletto (#) con le date. Per i numeri, è possibile usare le virgole decimali, i segni di dollaro e la notazione scientifica. Se l'operatore è LIKE, il valore può usare caratteri jolly. L'asterisco (*) e la percentuale (%) sono gli unici caratteri jolly consentiti e devono essere l'ultimo carattere nella stringa. Il valore non può essere Null.

Nota

Per includere le virgolette singole (') nel valore del filtro, usare due virgolette singole per rappresentarne una. Per applicare un filtro a O'Malley, ad esempio, la stringa di criteri deve essere "col1 = 'O''Malley'". Per includere le virgolette singole sia all'inizio sia alla fine del valore del filtro, racchiudere la stringa tra segni di cancelletto (#). Per applicare un filtro a '1', ad esempio, la stringa di criteri deve essere "col1 = #'1'#".

  • Non esiste alcuna precedenza tra gli operatori AND e OR. Le clausole possono essere raggruppate tra parentesi. Non è tuttavia possibile raggruppare clausole unite da un operatore OR e unire il gruppo a un'altra clausola con l'operatore AND, come indicato di seguito:
    (LastName = 'Smith' OR LastName = 'Jones') AND FirstName = 'John'

  • Costruire invece questo filtro come
    (LastName = 'Smith' AND FirstName = 'John') OR (LastName = 'Jones' AND FirstName = 'John')

  • In una clausola LIKE è possibile usare un carattere jolly all'inizio e alla fine del criterio. È ad esempio possibile usare LastName Like '*mit*'. In alternativa, con l'operatore LIKE è possibile usare un carattere jolly solo alla fine del criterio. Ad esempio: LastName Like 'Smit*'.

Le costanti di filtro semplificano la risoluzione dei conflitti di record singoli nella modalità di aggiornamento batch consentendo di visualizzare, ad esempio, solo i record interessati durante l'ultima chiamata al metodo UpdateBatch.

L'impostazione della proprietà Filter stessa potrebbe non riuscire a causa di un conflitto con i dati sottostanti. Questo errore, ad esempio, può verificarsi quando un record è già stato eliminato da un altro utente. In tal caso, il provider restituisce avvisi alla raccolta Errors Collection (ADO), ma non arresta l'esecuzione del programma. Si verifica un errore di run-time solo se sono presenti conflitti in tutti i record richiesti. Usare la proprietà Status Property (ADO Recordset) per individuare i record con conflitti.

L'impostazione della proprietà Filter su una stringa di lunghezza zero ("") produce lo stesso effetto che ha l'uso della costante adFilterNone.

Ogni volta che viene impostata la proprietà Filter, la posizione del record corrente diventa il primo record nel subset filtrato di record nell'oggetto Recordset. In modo analogo, quando la proprietà Filter viene cancellata, la posizione del record corrente diventa il primo record nell'oggetto Recordset.

Si supponga che un oggetto Recordset sia filtrato in base a un campo di tipo variant, ad esempio il tipo sql_variant. Si verifica un errore (DISP_E_TYPEMISMATCH o 80020005) quando i sottotipi del campo e i valori del filtro usati nella stringa di criteri non corrispondono. Si supponga ad esempio che:

  • Un oggetto Recordset (rs) contiene una colonna (C) del tipo sql_variant.
  • A una campo di questa colonna è stato assegnato un valore pari a 1 di tipo I4. La stringa dei criteri è impostata su rs.Filter = "C='A'" nel campo.

Questa configurazione genera l'errore di run-time. rs.Filter = "C=2" applicato allo stesso non genera tuttavia alcun errore. Il campo viene filtrato in base al set di record corrente.

Vedere la proprietà Bookmark Property (ADO) per una spiegazione dei valori dei segnalibri da cui è possibile compilare una matrice da usare con la proprietà Filter.

Solo i filtri in forma di stringhe di criteri influiscono sul contenuto di un oggetto Recordset persistente. Un esempio di stringa di criteri è OrderDate > '12/31/1999'. I filtri creati con una matrice di segnalibri o con un valore da FilterGroupEnum, non influiscono sul contenuto dell'oggetto Recordset persistente. Queste regole si applicano agli oggetti Recordset creati con cursori lato client o lato server.

Nota

Quando si applica il flag adFilterPendingRecords a un oggetto Recordset filtrato e modificato nella modalità di aggiornamento batch, l'oggetto Recordset risultante è vuoto se il filtro è basato sul campo chiave di una tabella a chiave singola e la modifica è stata apportata sui valori del campo chiave. L'oggetto Recordset risultante sarà non vuoto se una delle istruzioni seguenti è true:

  • Il filtro è basato su campi non chiave in una tabella a chiave singola.

  • Il filtro è basato su qualsiasi campo in una tabella con più chiavi.

  • Le modifiche sono state apportate ai campi non chiave in una tabella a chiave singola.

  • Le modifiche sono state apportate a qualsiasi campo in una tabella con più chiavi.

La tabella seguente riepiloga gli effetti di adFilterPendingRecords in combinazioni diverse di filtri e modifiche. La colonna a sinistra mostra le possibili modifiche. Le modifiche possono essere apportate a uno dei campi non chiave, sul campo chiave in una tabella a chiave singola oppure a uno dei campi chiave in una tabella con più chiavi. La riga superiore mostra il criterio di filtro. Le modifiche possono essere apportate a uno dei campi non chiave, al campo chiave in una tabella a chiave singola oppure a uno dei campi chiave in una tabella con più chiavi. Le celle intersecanti mostrano i risultati. Un segno + indica che l'applicazione di adFilterPendingRecords comporta un oggetto Recordset non vuoto. Un segno meno - indica un oggetto Recordset vuoto.

Combinazioni Non chiavi Chiave singola Più chiavi
Non chiavi + + +
Chiave singola + - N/D
Più chiavi + N/D +

Si applica a

Oggetto Recordset (ADO)

Vedere anche

Esempio delle proprietà Filter e RecordCount (VB)Esempio delle proprietà Filter e RecordCount (VC++)Metodo Clear (ADO)Proprietà dinamica Optimize (ADO)