📘 dbSetFilter [AS] – Define um filtro lógico para a área de trabalho atual
📝 Descrição
dbSetFilter [AS] – Permite definir um filtro lógico de visibilidade de registros para a área de trabalho atual (alias corrente).
|
📌 Sintaxe
| dbSetFilter( <bCondicao>, <cCondicao> ) |
🔣 Parâmetros
| Par |
Nome |
Tipo |
Descrição |
Default |
Obg |
Ref |
| 01 |
bCondicao |
Bloco |
Bloco com expressão lógica que determina a visibilidade dos registros (retorna .T. ou .F.). |
|
|
|
| 02 |
cCondicao |
Caracter |
Expressão literal equivalente ao bloco. Deve refletir exatamente o conteúdo do primeiro parâmetro. |
|
|
|
📤 Retorno
| Retorno |
Tipo |
Descrição |
| — |
— |
A função não possui retorno direto. Atua sobre o alias atual. |
🧩 Exemplo
#INCLUDE "TOTVS.CH"
User Function dbSetFilter()
Local cFiltro := 'A1_COD > "000001" '
dbSelectArea('SA1')
SA1->( dbSetFilter( { || &cFiltro }, cFiltro ) )
MsgInfo( dbFilter(), 'UniversoADVPL' )
Return( Nil )
📸 Resultado
📎 Informações adicionais
|
Quando um filtro é setado, os registros que não atendem a condição não ficam logicamente visíveis. Operações que dependem da visibilidade lógica ignorarão estes registros.
|
|
A expressão do filtro deve ser equivalente no bloco e na string. Diferenças entre elas produzem comportamento imprevisível.
A função dbSetFilter() é chamada internamente pelo comando SET FILTER TO.
Filtros atuam como se a tabela contivesse apenas os registros que atenderem a condição.
Funções de movimentação (como DBGoTop) respeitam o filtro; já DBGoTo() e RECORD não respeitam.
|
🔎 Observações e comportamento
| O ponteiro de registro não é reposicionado automaticamente. Utilize DBGoTop() para ativar o filtro. |
| A expressão de filtro é avaliada dinamicamente conforme a movimentação do ponteiro. |
| O alias filtrado é implicitamente ativado durante a avaliação da condição. |
| Expressões com campos de outras tabelas produzem efeitos imprevisíveis. |
| Alterar campos dentro do filtro também gera comportamento imprevisível. |
🚀 Performance e tráfego
|
Expressões de filtro são avaliadas no Application Server. Em bancos client/server, isso gera tráfego de registros pela rede.
O DBAccess otimiza filtros usando funções suportadas nativamente pelo banco.
Funções não suportadas tornam a expressão sempre verdadeira.
|
📂 Filtros – ADS Server / c-tree Server
|
Ambos suportam funções básicas como: DtoS(), SubStr(), $, AllTrim(), Left(), Right(), Str(), StrZero().
RDDs compatíveis: DBFCDX (CTREE), DBFCDXAX (ADS), CTREECDX.
|
📂 Filtros – DBAccess (TOPCONN)
Suporte depende do banco. DBAccess tenta aplicar o máximo possível da expressão diretamente na query.
📊 Funções suportadas por banco (DBAccess)
📁 Exemplo prático
Partindo de uma tabela com estrutura:
| CPOC |
C |
2 |
0 |
| CPON |
N |
12 |
2 |
| CPOD |
D |
8 |
0 |
Ao aplicar filtros e navegar pela tabela, o trace do DBAccess mostra a tradução das condições para queries SQL.
Gostou? Compartilhe com seus amigos e deixe um comentário! 😎
