dbSetFilter [AS]
Autor: Eurai Criado: 01/01/2016 Atualizado: 25/04/2025Descriçã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 de Código |
Indica um bloco de código AdvPL avaliado para determinar a visibilidade dos registros do alias enquanto filtrado. Ele expressa efetivamente a condição de filtro, onde o bloco de código deve retornar verdadeiro (.T.), caso o registro atual seja considerado pelo filtro, ou falso (.F.), caso o registro não deve ser considerado |
|||
02 | cCondicao |
Caracter |
Indica a representação literal da condição de filtro expressada no bloco de código. Trata-se de um parâmetro obrigatório, e deve refletir o conteúdo – fonte (source) do bloco de código usado no primeiro parâmetro, em caso de diferenças entre eles, o comportamento do filtro é imprevisível. Caso seja informada uma string em branco, é assumido automaticamente o código-fonte do bloco de código especificado |
Retorno
Retorno | Tipo | Descrição |
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 de filtro não estão logicamente visíveis. Isto significa que os registros filtrados não estão visíveis para as operações e instruções que atuam sob a visibilidade lógica das informações |
A expressão de filtro fornecida para a função deve retornar verdadeiro (.T.) caso o registro atual da tabela atenda à condição de filtro, caso contrário deve retornar falso (.F.). A expressão de filtro deve ser um bloco de código (bCondicao), e a equivalente condição em string (cCondicao), e ambas sendo fornecidas, elas devem expressar a mesma condição.A função DBSetFilter() é chamada internamente a partir do comando SET FILTER TO <cExp>. A utilização deste comando recebe a expressão AdvPL de filtro, e na pré-compilação do código-fonte AdvPL, realiza a chamada explícita da função DBSetFilter() com o bloco de código montado a partir da condição informada. A utilização do comando SET FILTER TO torna a codificação mais simples e legível, mesmo que internamente o resultado seja o mesmo.Ao aplicar um filtro em uma tabela aberta, esta passa a se comportar como se contivesse apenas os registros que atendem a condição de filtro especificada. A maior parte das funções que movem o ponteiro de registro atual respeita o filtro atualmente setado, exceto os comandos que trabalham com o número físico do registro (RECNO). Isto inclui a instrução DBGoTo() e comandos onde é especificada a cláusula RECORD <n> |
Observações e Comportamento
Ao executar a instrução DBSetFilter(), o ponteiro de registro atual não é reposicionado. Isto significa que o filtro não se torna ativo a menos que o ponteiro de registro seja movido em alguma direção. Normalmente utilizamos DBGoTop() para ativar o filtro, onde o ponteiro de registro será posicionado no primeiro registro logicamente válido dentro da expressão de filtro atual na ordem em uso. |
A expressão de filtro não é obrigatoriamente executada em um momento especifico e/ou em um ou vários registros. Sua execução é dinâmica, quando da determinação de visibilidade lógica de registros nas operações de posicionamento da RDD |
O contexto de execução (EVAL) da expressão de filtro está atrelado ao alias filtrado, que será implicitamente setado como alias corrente durante a avaliação da condição de filtro. |
Caso a expressão de filtro utilize informações externas ao alias atual, como campos de outras tabelas, os efeitos são imprevisíveis. |
Caso a expressão de filtro realize alguma alteração de status no alias atual, como por exemplo trocar o conteúdo de algum campo, os efeitos são imprevisíveis. |
Performance e tráfego de registros
O contexto de execução de filtros AdvPL em sua origem é independente de RDD, e por se tratar de um comportamento da linguagem, a expressão de filtro é avaliada pelo servidor de aplicação (Application Server), na execução das instruções de movimentação de ponteiro de registro. Quando utilizada uma arquitetura client/server de banco de dados (como por exemplo ADS Server, c-tree Server , TOPConnect, DBAccess), isto torna necessária a leitura dos registros no banco de dados e o tráfego dos registros para a avaliação da expressão de filtro no Application Server, onde está sendo executado o programa AdvPL que definiu o filtro.A linguagem AdvPL possui otimizações para atender a determinadas condições de filtro, onde o filtro é aplicado total ou parcialmente diretamente na aplicação servidora de banco de dados, sendo mais eficiente, performático e eliminando o overhead de rede gerado pelo tráfego de registros. Em linhas gerais, tabelas utilizando uma RDD com componentes client/server (ADS Server, c-tree Server e/ou DBAccess) executam a expressão de filtro na íntegra diretamente na aplicação servidora de banco, desde que o filtro não faça uso de nenhuma função da linguagem AdvPL, mesmo que função básica e/ou nativa da linguagem, e utilize apenas os operadores binários > (maior), >= (maior ou igual), < (menor), <= (menor ou igual), <> ou != (diferente) e = (igual), e expressões lógicas com os operadores .AND., .OR. e/ou .NOT., e devem preferencialmente utilizar na condição de filtro campos da tabela que façam parte da ordem de índice em uso no momento.As características e pré-requisitos do comportamento de filtros executados diretamente na aplicação servidora de bancos de dados, e suporte a operadores e funções nativas para execução de filtro diretamente no banco são abortadas dentro dos tópicos de comportamentos específicos de acordo com a RDD e aplicação servidora de banco utilizada. |
Filtros em tabelas utilizando ADS Server e/ou c-tree Server
Ambos os engines suportam o uso de funções básicas da linguagem AdvPL na montagem da expressão de filtro, e executam de modo nativo o filtro na aplicação servidora. Funções como AllTrim(), Dtos(), Left(), Right(), operador $ (contido em), Str(), StrZero() e afins são tratadas diretamente pelo ADS Server e/ou c-tree Server. Englobam os acessos realizados através das seguintes RDDs sob as seguintes condições: RDD DBFCDX – em ambiente configurado com LocalFiles=CTREE, utilizando um c-tree Server para controle dos dicionários. RDD DBFCDXAX – em ambiente configurado para base de dados principal com ADS Server e repositório ADS (RpoDb=ADS). RDD CTREECDX – em ambiente configurado para base de dados principal com c-tree Server e repositorio c-tree (RPODB=CTREE). |
Filtros em tabelas utilizando DBaccess
Através do DBAccess, criamos e acessamos tabelas em bancos de dados relacionais usando a RDD TOPCONN, em diversos bancos de dados homologados. As funcionalidades extendidas de filtro, como suporte a algumas funções básicas da linguagem AdvPL foram implementadas no DBAccess de forma diferenciada para cada banco de dados, de acordo com os recursos disponíveis nos bancos, capazes de prover ou emular o comportamento original de um filtro AdvPL. Quando setada uma expressão de filtro em uma tabela acessada pela RDD TOPCONN, através de um programa AdvPL, caso existam comparações suportadas e não suportadas na mesma expressão, o DBAccess faz uma redução do filtro, tentando aproveitar todas as partes da expressão suportadas, para filtrar o que for possível através das queries de busca de dados do DBAccess, e minimizar tráfego de rede e recuperação desnecessária de registros. Qualquer condição não suportada pelo DBAccess e enviada a ele resultará em uma comparação sempre verdadeira considerando o primeiro campo da tabela (no ERP, em geral é o campo _FILIAL).
Observe, a seguir, o suporte para funções AdvPL em filtro implementado no DBAccess: |
FUNÇÕES ADVPL/BANCO |
MICROSOFT SQL |
ORACLE |
IBM DB2 |
INFORMIX |
SYBASE |
POSTGRESQL |
MYSQL |
DToS (cpo) |
SIM |
SIM |
SIM |
SIM |
SIM |
SIM |
SIM |
SubStr(s,n,n) |
SIM |
SIM |
SIM |
SIM |
SIM |
SIM |
SIM |
$ (operador) |
SIM |
SIM |
SIM |
SIM |
SIM |
SIM |
SIM |
Empty() |
SIM |
SIM |
SIM |
SIM |
NÃO |
SIM |
NÃO |
AllTrim() |
SIM |
SIM |
SIM |
SIM |
NÃO |
NÃO |
NÃO |
Lower() |
SIM |
SIM |
SIM |
SIM |
NÃO |
SIM |
NÃO |
Upper() |
SIM |
SIM |
SIM |
SIM |
NÃO |
SIM |
NÃO |
Left() |
SIM |
SIM |
SIM |
NÃO |
NÃO |
NÃO |
NÃO |
Right() |
SIM |
NÃO |
SIM |
NÃO |
NÃO |
NÃO |
NÃO |
Space() |
SIM |
SIM |
SIM |
NÃO |
NÃO |
NÃO |
NÃO |
StrTran() |
SIM |
SIM |
SIM |
NÃO |
SIM |
NÃO |
NÃO |
Len() |
NÃO |
SIM |
SIM |
SIM |
NÃO |
NÃO |
NÃO |
CHR() |
SIM |
SIM |
NÃO |
NÃO |
NÃO |
NÃO |
NÃO |
ASC() |
SIM |
SIM |
SIM |
NÃO |
NÃO |
NÃO |
NÃO |
As únicas funcionalidades suportadas de modo nativo ao aplicar um filtro AdvPL em todos os bancos de dados são: Dtos (campo) -> Onde a expressão é removida, pois o DBAccess grava um campo “D” Data do ADVPL no banco como string, no formato “AAAAMMDD”, SubStr(campo ,nStart ,nLen) , e o operador $ (contido em expressão string). Quaisquer outras funções utilizadas em uma condição de filtro serão avaliadas no servidor de aplicação (TOTVS/ByYou Application Server). |
Exemplo
Partindo de uma tabela com a seguinte estrutura :
|
Ao aplicarmos os filtros abaixo e navegar na tabela, é possível verificar através do recurso de trace de conexão do DBAccess que as condições foram traduzidas para condições nas queries montadas pelo DBAccess para busca dos dados. Os exemplos abaixo, foram obtidos com um trace feito em uma conexão do Application Server com um DBAccess 4.2 utilizando um Microsoft SQL Server 2005, onde o programa seta o filtro usando o comando SET FILTER TO (expressão), e após setar o filtro executa um DBGoTop() na tabela.
Gostou? Compartilhe com seus amigos e deixe um comentário! 😎
Discussão (0)
Sem comentários ainda
Realize o LOGIN no site para poder comentar