Tempo de leitura: 4 minutos
No desenvolvimento de rotinas no ERP Protheus, o controle preciso sobre o ponteiro das tabelas é o que diferencia um código estável de um sistema propenso a erros. Muitas vezes, após realizar filtros ou contagens, o ponteiro da tabela acaba no final do arquivo (EOF), e é necessário retornar ao início para processar os dados. A função DBGoTop em ADVPL é o comando nativo responsável por esse reposicionamento lógico, sendo um conceito vital dentro de ADVPL no Protheus: Dados e Estrutura.
Neste guia completo, vamos explorar o funcionamento da DBGoTop, entender como ela interage com índices e filtros no SQL e Banco de Dados e aplicar as melhores práticas para garantir que suas varreduras de dados sejam sempre precisas.
O que é a função DBGoTop e para que serve?
A função DBGoTop em ADVPL tem como objetivo posicionar o ponteiro de leitura no primeiro registro lógico da área de trabalho ativa. É importante destacar o termo “lógico”: o primeiro registro não é necessariamente o primeiro que foi gravado fisicamente no banco de dados, mas sim o primeiro de acordo com a ordem (índice) e os filtros aplicados no momento.
Sintaxe e Funcionamento
A sintaxe é direta e não requer parâmetros:
DBGoTop()
Sempre que você utiliza comandos como Count To ou finaliza um loop `While !
Eof()`, o ponteiro da tabela estará posicionado no final. Sem o uso da DBGoTop, qualquer tentativa subsequente de leitura falhará, pois o sistema entenderá que não há mais registros a processar.
Sintaxe:
DBGoTop()
Parâmetro(s):
Nenhum.
Observações:
- A sequência lógica depende da ordem e do filtro ativo na tabela corrente. Portanto, o primeiro registro lógico pode não ser o primeiro registro físico.
Exemplo da função DBGoTop em ADVPL: Vamos supor que nós tenhamos 5 registros na tabela SA2(Fornecedores) do TOTVS Protheus conforme os dados, nesse caso usamos a função DBGoTop para garantir o posicionamento no primeiro registro lógico de SA2, assim a mensagem no código ADVPL abaixo será: “O nome do primeiro fornecedor de SA2 é:FORNECEDOR 1“, já que foi feito o posicionamento para o início dos registros de SA2.
| FILIAL | CÓDIGO | NOME | CNPJ |
| 0101 | 000001 | FORNECEDOR 1 | 99999999999999 |
| 0101 | 000002 | FORNECEDOR 2 | 88888888888888 |
| 0101 | 000003 | FORNECEDOR 3 | 77777777777777 |
| 0101 | 000004 | FORNECEDOR 4 | 66666666666666 |
| 0101 | 000005 | FORNECEDOR 5 | 55555555555555 |
//Bibliotecas
#Include "Protheus.ch"
#INCLUDE "TBICONN.CH"
#INCLUDE "topconn.ch"
#include "TOTVS.CH"
/*/{Protheus.doc} fDBGoTop
Exemplo da função DBGoTop em ADVPL
@type function
@author Adilio Costa
@since 06/12/2023
@version 1.0
@?Inscreva-se no Blog ProtheusAdvpl:
https://www.protheusadvpl.com.br
@?Inscreva-se no Canal ProtheusAdvpl:
https://www.youtube.com/protheusadvpl
@?Siga-nos no Instagram:
https://www.instagram.com/protheusadvpl
@?Conheça os Cursos e Formações do Protheus:
https://cursos-e-formacoes-protheusadvpl.gr-site.com/
@Participe de nossas comunidades no WhatsApp:
-Comunidade Protheus Backoffice:https://chat.whatsapp.com/KMUIAjwZ6EZ6eAHsLkPTyb
-Comunidade Protheus-RH:https://chat.whatsapp.com/L5dUyAna6xU4ylG5DUgfOW
-Comunidade Protheus-Programação:https://chat.whatsapp.com/LsD6z0apdqKHlOz67bcaEn
-Comunidade Protheus-Framework:https://chat.whatsapp.com/BzUFpjaSnTC3vtsfa77jmG
|Se esse conteúdo foi útil pra você nos ajude divulgando
ele e nossas redes sociais!!|
/*/
User Function fDBGoTop()
Local aArea := GetArea() //Salvando a área atual
//Seleciona a tabela SA2 como a área ativa
DBSelectArea("SA2")
//Seleciona o 1 índice de SA2 -> A2_FILIAL+A2_COD+A2_LOJA
SA2->(DBSetOrder(1))
//Posiciona no prímeiro registro lódigo de SA2
SA2->(DBGoTop())
FWAlertInfo("O nome do primeiro fornecedor de SA2 é:"+SA2->A2_NOME,"Função DBGoTop")
//Restaurando o ambiente salvo
RestArea(aArea)
Return
Boas Práticas e Performance
No dia a dia do ADVPL Avançado no Protheus, o uso da DBGoTop deve ser estratégico. Aqui estão as diretrizes de ouro:
- Após Filtros e Queries: Sempre que aplicar um SetFilter ou abrir uma query via TCGenQry, execute a DBGoTop para garantir que o ponteiro não comece em um local indefinido.
- Verificação de Alias: Antes de mover o ponteiro, valide se a área está aberta com a função Select.
- Cuidado com Tabelas Grandes: Em tabelas com milhões de registros e filtros complexos, a DBGoTop pode forçar o banco de dados a realizar uma busca custosa. Certifique-se de que seus índices no SIGACFG estão otimizados.
Conclusão
A função DBGoTop em ADVPL é um dos comandos fundamentais do ADVPL. Ela garante a previsibilidade do seu código, permitindo que você navegue pelos dados com a certeza de estar começando do ponto correto. Dominar o controle de ponteiros é essencial para qualquer desenvolvedor que deseja criar rotinas robustas e integradas ao SQL e Banco de Dados do Protheus.
Links de referência(s):
Conteúdos relacionados
É isso aí, finalizamos aqui mais um post no Blog ProtheusAdvpl. Caso tenha ficado alguma dúvida deixe seu comentário ou nos envie um e-mail para adiliocosta@protheusadvpl.com.br, até um próximo post, grande abraço e fica com Deus.
