Propriedade Filter (ADO)

Aplica-se ao: Access 2013, Office 2013

Indica um filtro para os dados em um Recordset.

Configurações e valores retornados

Define ou retorna um valor Variant, que pode conter:

• Sequência de critérios — uma cadeia de caracteres formada por uma ou mais cláusulas individuais concatenadas com os operadores AND ou OR.

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

• Um valor FilterGroupEnum.

Comentários

Use a propriedade Filter para filtrar de maneira seletiva os registros de um objeto Recordset. O Recordset filtrado torna-se o cursor atual. Outras propriedades que retornam valores com base no cursor atual são afetadas, como AbsolutePosition, AbsolutePage, RecordCount e PageCount. Isso ocorre porque a definição da propriedade Filter para um valor específico moverá o registro atual para o primeiro registro que satisfaça o novo valor.

A cadeia de critérios é composta por cláusulas no formulário FieldName-Operator-Value (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, "). 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'"). Use as seguintes diretrizes para as sequências de critérios:

• FieldName deve ser um nome de campo válido do Recordset. Se o nome do campo contiver espaços, você deverá colocar o nome entre colchetes.

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

• O valor é o valor com o qual você comparará os valores de campo (por exemplo, 'Smith', #24/8/95#, 12.345 ou $50.00). Use aspas individuais com cadeias de caracteres e sinais de libra (#) com datas. Para números, você pode usar vírgulas decimais, símbolos de dólar e notação científica. Se Operator for LIKE, Value poderá usar curingas. Apenas os curingas asterisco (*) e porcentagem (%) são permitidos e devem ser o último caractere da sequência. Value não pode ser nulo.

  Observação

  [!OBSERVAçãO] Para incluir aspas simples (') no filtro Value, use duas aspas simples para representar uma. Por exemplo, para filtrar em O'Malley, a sequência de critérios deve ser "col1 = 'O''Malley'". Para incluir aspas simples no início e no final do valor de filtragem, coloque a sequência entre símbolos de libra (#). Por exemplo, para filtrar em '1', a sequência 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 ingressadas por um OR e, em seguida, ingressar o grupo em outra cláusula com um AND, como no seguinte snippet de código:
  (LastName = 'Smith' OR LastName = 'Jones') AND FirstName = 'John'

• Em vez disso, você deve construir esse filtro como
  (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, LastName Like '*mit*') ou somente no final do padrão (por exemplo, LastName Like 'Smit*').

As constantes de filtragem tornam mais fácil resolver conflitos individuais de registro durante o modo de atualização em lote, permitindo que você exiba, por exemplo, apenas os registros que foram afetados durante a última chamada do método UpdateBatch.

A definição da propriedade Filter pode falhar devido a um conflito com os dados de base (por exemplo, um registro já foi excluído por outro usuário). Nesse caso, o provedorretorna avisos para a coleção Errors, mas não paralisa a execução do programa. Um erro de tempo de execução ocorre apenas quando houver conflitos em todos os registros solicitados. Use a propriedade Status para localizar registros com conflitos.

Definir a propriedade Filter para uma sequência de comprimento zero ("") tem o mesmo efeito que usar a constante adFilterNone.

Sempre que a propriedade Filter for definida, a posição atual do registro passará para o primeiro registro no subconjunto filtrado de registros no Recordset. Da mesma forma, quando a propriedade Filter estiver em branco, a posição atual do registro passará para o primeiro registro no Recordset.

Consulte a propriedade Bookmark para obter uma explicação sobre valores de indicadores a partir dos quais é possível construir uma matriz para usar com a propriedade Filter.

Somente filtros na forma de Cadeias de Caracteres de Critério (por exemplo, OrderDate > '31/12/1999') afetam o conteúdo de um Conjunto de Registros persistente. Filters criados com uma Matriz de Bookmarks ou usando um valor de FilterGroupEnum não afetarão o conteúdo de um Recordset persistente. Essas regras aplicam-se a Recordsets criados com cursores do lado do cliente e do servidor.

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