GetArea()FunçãoObrigatório
Não recebe argumentos. Retorna um array com Alias(), IndexOrd() e Recno() do ambiente capturado.
FUNDAMENTOPublicado
Preservação de áreas com GetArea e RestArea
aArea := GetArea() // ... processamento ... RestArea(aArea)Preserve alias, ordem e registro antes de navegar por tabelas e devolva ao chamador o mesmo contexto de trabalho.
Visão geral
Em AdvPL, uma rotina que seleciona aliases, altera ordens ou movimenta registros pode modificar o ambiente que o código chamador esperava continuar usando. GetArea() captura o alias ativo, a ordem selecionada e o registro corrente; RestArea() restaura esse conjunto. Quando a rotina também manipula um alias conhecido, preserve tanto a área geral quanto a área específica. Restaure primeiro o alias manipulado e, por último, a área geral, pois a última área restaurada permanece ativa. A documentação e os exemplos atuais também apresentam FWGetArea() e FWRestArea() como evolução no Framework; confirme a disponibilidade na LIB do ambiente e use o par adotado pelo projeto de forma consistente.
Sintaxe
aArea := GetArea() // ... processamento ... RestArea(aArea)Parâmetros
Alias->(GetArea())ExpressãoOpcional
Captura o estado de uma área específica sem torná-la definitivamente a área ativa da rotina.
RestArea(aArea)FunçãoObrigatório
Recebe o array criado por GetArea() e restaura alias, ordem e registro. A última restauração determina a área ativa.
Retorno
GetArea() retorna um array com o alias, a ordem e o número do registro atuais. RestArea() usa esse array para recompor o ambiente salvo.
Preservar a área ativa
#Include "TOTVS.ch"
User Function ExConsultaCliente()
Local aAreaAnterior := GetArea()
Local cNomeCliente := ""
DbSelectArea("SA1")
SA1->(DbSetOrder(1))
If SA1->(DbSeek(xFilial("SA1") + "000001"))
cNomeCliente := SA1->A1_NOME
EndIf
RestArea(aAreaAnterior)
Return cNomeClienteResultado esperado
A consulta pode usar SA1 sem deixar essa tabela, sua ordem ou seu registro como contexto ativo do chamador.
Preservar a área geral e um alias específico
#Include "TOTVS.ch"
User Function ExValidaProduto()
Local aAreaAnterior := GetArea()
Local aAreaSB1 := SB1->(GetArea())
Local lEncontrado := .F.
DbSelectArea("SB1")
SB1->(DbSetOrder(1))
lEncontrado := SB1->(DbSeek(xFilial("SB1") + "000001"))
// Primeiro restaura o alias manipulado.
SB1->(RestArea(aAreaSB1))
// Por último restaura a área que o chamador deixou ativa.
RestArea(aAreaAnterior)
Return lEncontradoResultado esperado
SB1 recupera sua posição anterior e a rotina devolve ao chamador o ambiente geral que recebeu.
Versão com funções do Framework
#Include "TOTVS.ch"
User Function ExAreaFramework()
Local aAreaAnterior := FWGetArea()
Local aAreaSC5 := SC5->(FWGetArea())
DbSelectArea("SC5")
SC5->(DbSetOrder(1))
SC5->(DbGoTop())
FWRestArea(aAreaSC5)
FWRestArea(aAreaAnterior)
ReturnResultado esperado
O mesmo padrão é aplicado com as funções do Framework, desde que estejam disponíveis na LIB homologada.
- Capture a área antes de DbSelectArea(), DbSetOrder(), DbGoTo(), DbSeek() ou outra operação que altere o contexto recebido.
- Se um alias específico será manipulado, salve também Alias->(GetArea()). Isso protege sua ordem e seu registro mesmo quando ele não era a área ativa.
- Restaure as áreas específicas antes da área geral; a última chamada de RestArea() define qual alias ficará ativo.
- Evite Return, Break ou desvios que saiam da rotina antes das restaurações. Centralize a saída sempre que isso tornar o fluxo mais seguro.
- Em pontos de entrada e funções chamadas pelo padrão, trate a preservação como parte do contrato: o Protheus deve continuar do mesmo contexto em que chamou a customização.
- Para código baseado no Framework, avalie FWGetArea() e FWRestArea() conforme a LIB homologada e o padrão do projeto.
- Salvar apenas a área geral não protege, necessariamente, a posição anterior de cada alias adicional manipulado.
- Restaurar a área geral primeiro e outra área depois deixa o segundo alias ativo, alterando o contexto do chamador.
- O array salvo representa um estado temporário; não deve ser tratado como referência permanente a um registro que pode ter sido excluído ou reposicionado por concorrência.
- Preservar áreas não substitui bloqueio de registros, transações, tratamento de erros ou validação do retorno de DbSeek().
- Misturar exemplos antigos e atuais sem verificar a LIB pode introduzir funções indisponíveis no ambiente utilizado.