GetArea()FunctionRequired
Takes no arguments and returns an array containing Alias(), IndexOrd() and Recno().
FOUNDATIONPublished
Work-area preservation with GetArea and RestArea
aArea := GetArea() // ... processing ... RestArea(aArea)Preserve the alias, order and record before navigating tables, then return the same work context to the caller.
Overview
An AdvPL routine that selects aliases, changes orders or moves records can alter the environment expected by its caller. GetArea() captures the active alias, selected order and current record; RestArea() restores that set. When a known alias is also manipulated, preserve both the general area and that specific area. Restore the manipulated alias first and the general area last, because the last restored area remains active. Current examples also present FWGetArea() and FWRestArea() as Framework alternatives; confirm availability in the target LIB and consistently use the pair adopted by the project.
Syntax
aArea := GetArea() // ... processing ... RestArea(aArea)Parameters
Alias->(GetArea())ExpressionOptional
Captures a specific work area without permanently making it the routine active area.
RestArea(aArea)FunctionRequired
Receives the array returned by GetArea() and restores alias, order and record. The last restore determines the active area.
Return value
GetArea() returns an array containing the current alias, order and record number. RestArea() uses it to rebuild the saved environment.
Preserve the active area
#Include "TOTVS.ch"
User Function ExCustomerLookup()
Local aPreviousArea := GetArea()
Local cCustomerName := ""
DbSelectArea("SA1")
SA1->(DbSetOrder(1))
If SA1->(DbSeek(xFilial("SA1") + "000001"))
cCustomerName := SA1->A1_NOME
EndIf
RestArea(aPreviousArea)
Return cCustomerNameExpected result
The lookup uses SA1 without leaving its context active for the caller.
Preserve the general and a specific area
#Include "TOTVS.ch"
User Function ExProductCheck()
Local aPreviousArea := GetArea()
Local aSB1Area := SB1->(GetArea())
Local lFound := .F.
DbSelectArea("SB1")
SB1->(DbSetOrder(1))
lFound := SB1->(DbSeek(xFilial("SB1") + "000001"))
SB1->(RestArea(aSB1Area))
RestArea(aPreviousArea)
Return lFoundExpected result
SB1 and the caller general environment are both restored.
Framework functions
#Include "TOTVS.ch"
User Function ExFrameworkArea()
Local aPreviousArea := FWGetArea()
Local aSC5Area := SC5->(FWGetArea())
DbSelectArea("SC5")
SC5->(DbSetOrder(1))
SC5->(DbGoTop())
FWRestArea(aSC5Area)
FWRestArea(aPreviousArea)
ReturnExpected result
The same pattern is used with Framework functions available in the supported LIB.
- Capture the area before operations that change the received context.
- Also save Alias->(GetArea()) for every known alias whose position will be changed.
- Restore specific areas before the general area.
- Avoid exits that bypass restoration; centralize the routine exit when useful.
- Treat preservation as part of the contract of entry points and standard callbacks.
- Evaluate FWGetArea() and FWRestArea() according to the supported LIB and project conventions.
- Saving only the general area does not necessarily protect every additional alias.
- Restoring the general area first and another alias afterward changes the caller active context.
- A saved array is a temporary state, not a permanent record reference.
- Area preservation does not replace locks, transactions, error handling or DbSeek() result validation.
- Verify Framework function availability in the deployed LIB.