Propriedade Filter

Indica um filtro para dados em um Conjunto de Registros.

Configurações e valores retornados

Define ou retorna um valor Variant, que pode conter um dos seguintes itens:

• Cadeia de caracteres de critérios: uma cadeia de caracteres composta por uma ou mais cláusulas individuais concatenadas com operadores AND ou OR.

• Matriz de indicadores: uma matriz de valores de indicador exclusivos que apontam para registros no objeto Recordset.

• Um valor FilterGroupEnum.

Comentários

Use a propriedade Filter para exibir seletivamente os registros em um objeto Recordset. O Recordset filtrado torna-se o cursor atual. Outras propriedades que retornam valores com base no cursor atual são afetadas, por exemplo, Propriedade AbsolutePosition (ADO),Propriedade AbsolutePage (ADO), Propriedade RecordCount (ADO)e Propriedade PageCount (ADO). A definição da propriedade Filter como um novo valor específico move o registro atual para o primeiro registro que satisfaz o novo valor.

A cadeia de caracteres de critérios é feita de cláusulas no formulário FieldName-Operator-Value do formulário (por exemplo, "LastName = 'Smith'"). Você pode criar cláusulas compostas concatenando cláusulas individuais com AND (por exemplo, "LastName = 'Smith' AND FirstName = 'John'") ou OR (por exemplo, "LastName = 'Smith' OR LastName = 'Jones'"). Para cadeias de caracteres de critério, use as seguintes diretrizes:

• FieldName precisa ser um nome de campo válido do Recordset. Se o nome do campo contém espaços, você precisa colocar o nome dentro de colchetes.

• O operador precisa ser um dos seguintes: <,>, <=, >=, <>,= ou LIKE.

• Valor é o valor com o qual você comparará os valores de campo (por exemplo, 'Smith', #8/24/95#, 12.345 ou $50,00). Use aspas simples com cadeias de caracteres e sinais de libra (#) com datas. Em números, você pode usar pontos decimais, sinais de dólar e notação científica. Se Operator for LIKE, Value poderá usar caracteres curinga. Somente os curingas asterisco (*) e o sinal percentual (%) são permitidos, e eles devem ser o último caractere na cadeia de caracteres. O valor não pode ser nulo.

Observação

Para incluir aspas simples (') no Value do filtro, use duas aspas simples para representar uma. Por exemplo, para filtrar por O'Malley, a cadeia de caracteres de critérios deve ser "col1 = 'O''Malley'". Para incluir aspas simples no início e no final do valor do filtro, coloque a cadeia de caracteres com sinais de libra (#). Por exemplo, para filtrar por '1', a cadeia de caracteres de critérios deve ser "col1 = #'1'#".

• Não há precedência entre AND e OR. As cláusulas podem ser agrupadas entre parênteses. No entanto, você não pode agrupar cláusulas unidas por OR e, em seguida, unir o grupo a outra cláusula com AND, como no seguinte snippet de código:
  (LastName = 'Smith' OR LastName = 'Jones') AND FirstName = 'John'

• Em vez disso, você construiria esse filtro desta forma
  (LastName = 'Smith' AND FirstName = 'John') OR (LastName = 'Jones' AND FirstName = 'John')

• Em uma cláusula LIKE, você pode usar um curinga no início e no final do padrão. Por exemplo, você pode usar LastName Like '*mit*'. Ou, com LIKE, você pode usar um curinga somente no final do padrão. Por exemplo, LastName Like 'Smit*'.

As constantes de filtro facilitam a resolução de conflitos de registro individuais durante o modo de atualização em lote permitindo que você exiba, por exemplo, apenas os registros que foram afetados durante a última chamada de Método UpdateBatch.

A configuração da própria propriedade Filter pode falhar devido a um conflito com os dados subjacentes. Por exemplo, essa falha pode acontecer quando um registro já foi excluído por outro usuário. Nesse caso, o provedor retorna avisos para a Coleção de Erros (ADO), mas não interrompe a execução do programa. Um erro no tempo de execução ocorre somente se há conflitos em todos os registros solicitados. Use a Propriedade Status (Conjunto de registros ADO) para localizar registros com conflitos.

A definição da propriedade Filter como uma cadeia de caracteres de comprimento zero ("") tem o mesmo efeito de usar a constante adFilterNone.

Sempre que a propriedade Filter é definida, a posição atual do registro se move para o primeiro registro no subconjunto filtrado de registros no Recordset. Da mesma forma, quando a propriedade Filter é desmarcada, a posição atual do registro se move para o primeiro registro no Recordset.

Digamos que um Recordset seja filtrado com base em um campo de algum tipo de variante, como o tipo sql_variant. Um erro (DISP_E_TYPEMISMATCH ou 80020005) ocorre quando os subtipos dos valores de campo e filtro usados na cadeia de caracteres de critérios não correspondem. Por exemplo, suponha:

• Um objeto Recordset (rs) contém uma coluna (C) do tipo sql_variant.
• E um campo dessa coluna recebeu um valor de 1 do tipo I4. A cadeia de caracteres de critérios é definida como rs.Filter = "C='A'" no campo.

Essa configuração produz o erro durante o tempo de execução. No entanto, rs.Filter = "C=2" aplicado no mesmo campo não produzirá nenhum erro. E o campo é excluído no filtro do conjunto de registros atual.

Confira a Propriedade Bookmark (ADO) para obter uma explicação dos valores de indicador dos quais você pode criar uma matriz para usar com a propriedade Filter.

Somente filtros na forma de cadeias de caracteres de critério afetam o conteúdo de um Recordsetpersistente. Um exemplo de uma cadeia de caracteres de critérios é OrderDate > '12/31/1999'. Os filtros criados com uma matriz de indicadores ou com o uso de um valor de FilterGroupEnum não afetam o conteúdo do Recordsetpersistente. Essas regras se aplicam a conjuntos de registros criados com cursores do lado do cliente ou do servidor.

Observação

Quando você aplica o sinalizador adFilterPendingRecords a um Recordset filtrado e modificado no modo de atualização em lote, o Recordset resultante fica vazio se a filtragem foi baseada no campo de chave de uma tabela de chave única e a modificação foi feita nos valores do campo de chave. O Recordset resultante não estará vazio se uma das seguintes instruções for verdadeira:

• A filtragem foi baseada em campos não chave em uma tabela de chave única.

• A filtragem foi baseada em qualquer campo em uma tabela com várias chaves.

• Modificações foram feitas em campos não chave em uma tabela de chave única.

• Modificações foram feitas em qualquer campo em uma tabela com várias chaves.

A tabela a seguir resume os efeitos de adFilterPendingRecords em diferentes combinações de filtragem e modificações. A coluna à esquerda mostra as possíveis modificações. As modificações podem ser feitas em qualquer um dos campos não chaveados, no campo de chave em uma tabela de chave única ou em qualquer um dos campos de chave em uma tabela com várias chaves. A linha superior mostra o critério de filtragem. A filtragem pode se basear em qualquer um dos campos não chaveados, no campo de chave em uma tabela de chave única ou em qualquer um dos campos de chave em uma tabela com várias chaves. As células de interseção mostram os resultados. Um sinal de adição + significa que a aplicação de adFilterPendingRecords resulta em um Recordset não vazio. Um sinal de menos - significa um Recordset vazio.

Combinações	Não chaves	Chave Única	Várias Chaves
Não chaves	+	+	+
Chave Única	+	-	N/D
Várias Chaves	+	N/D	+

Aplica-se A

Objeto Recordset (ADO)

Consulte Também

Exemplo das propriedades Filter e RecordCount (VB)Exemplo das propriedades Filter e RecordCount (VC++)Método Clear (ADO)Optimize Property-Dynamic (ADO)