FUNCTIONPublished

DbSelectArea

DbSelectArea( <nArea> | <cAlias> ) --> Nil

Selects the active work area by number or by an already open alias.

DatabaseAliasWorkareaCurrent area

01 · OVERVIEW

Overview

DbSelectArea() makes an open work area become the current work area for the process. It does not open a table by itself: actual table opening is done by DbUseArea(), by Protheus opening routines, or by the environment’s on-demand mechanisms. After selection, database operations without an explicit alias operate on the selected area.

02 · SYNTAX

Syntax

DbSelectArea( <nArea> | <cAlias> ) --> Nil

03 · PRACTICAL EXAMPLE

Selecting an already open area

User Function ExDbSelectArea()
    DbSelectArea("SA1")
    DbSetOrder(1)
    DbGoTop()

    ConOut(SA1->A1_NOME)
Return

Expected result

SA1 becomes the current work area. DbSetOrder() and DbGoTop() act on SA1 because no other area was explicitly informed.

04 · PRACTICAL EXAMPLE

Preserving and restoring the current area

User Function ExSafeArea()
    Local nPreviousArea := Select()

    DbSelectArea("SA2")
    SA2->(DbSetOrder(1))
    SA2->(DbGoTop())
    ConOut(SA2->A2_NOME)

    DbSelectArea(nPreviousArea)
Return

Expected result

The routine queries SA2 and then restores the area that was active before execution. Select() also preserves the case where no area was selected.

05 · PRACTICAL EXAMPLE

Aliased expression without changing the current area

User Function ExAliased()
    Local cSupplierName := ""

    cSupplierName := SA2->(A2_NOME)
    SA2->(DbSetOrder(1))
    SA2->(DbGoTop())

    ConOut(cSupplierName)
Return

Expected result

The aliased expression executes the read or function in the SA2 context without leaving SA2 as the current area for the rest of the program.

BEST PRACTICES

Confirm that the alias is already open before selecting it.
Use Select() or GetArea()/RestArea() when you need to preserve and restore the original area.
In routines that touch several tables, prefer aliased expressions such as SA1->(DbGoTop()) to avoid side effects on the current area.
DbSelectArea(0) selects a free area; it is useful before opening a new alias, but it is not the same as opening a table automatically.

COMMON PITFALLS

DbSelectArea("SA1") does not open the SA1 table by itself. If the alias does not exist, behavior depends on context and may result in an alias error or trigger Protheus on-demand handling.
Saving only Alias() may fail when no alias is selected; Select() also preserves the zero-area situation.
Changing the current area inside helper functions without restoring it can break the caller.
Do not use DbSelectArea() as a replacement for DbUseArea() when the goal is to physically open a table.

DbSelectArea

Overview

Syntax

Selecting an already open area

Preserving and restoring the current area

Aliased expression without changing the current area

Related content

Comments