cAliasCaractereRequired
Alias of the table to search.
FUNCTIONPublished
Posicione
Posicione( <cAlias>, <nOrdem>, <cSeek>, <cField>, [cNickName] ) → xRetSearches an indexed record and returns one field value directly.
Overview
Posicione() combines table selection, index selection, key lookup and field reading in one call. It is useful for retrieving related information without repeatedly writing DbSelectArea(), DbSetOrder(), DbSeek() and field access. The function changes the queried alias work area and record pointer, so use it carefully when a routine works with multiple tables.
Syntax
Posicione( <cAlias>, <nOrdem>, <cSeek>, <cField>, [cNickName] ) → xRetParameters
nOrdemNuméricoRequired
Index order number; ignored when cNickName is supplied.
cSeekCaractereRequired
Lookup key assembled according to the selected index expression.
cFieldCaractereRequired
Name of the field whose value is returned.
cNickNameCaractereOptional
Optional index nickname; when supplied, it replaces nOrder.
Return value
Returns the value of cField in its AdvPL type. When no key is found, handle the value according to the business rule and the expected field type.
Customer name from an invoice
User Function ExPosicioneCustomer()
Local cCustomerName := ""
cCustomerName := Posicione( ;
"SA1", 1, ;
xFilial("SA1") + SF2->F2_CLIENTE + SF2->F2_LOJA, ;
"A1_NOME" ;
)
MsgInfo(cCustomerName, "Customer")
ReturnExpected result
The function finds the customer and returns A1_NOME.
Protected product lookup
User Function ExPosicioneProduct()
Local aArea := GetArea()
Local cDescription := Posicione("SB1", 1, xFilial("SB1") + "000001", "B1_DESC")
RestArea(aArea)
MsgInfo(cDescription, "Product")
ReturnExpected result
The original work area and pointer are restored after the lookup.
Index nickname
// See the Portuguese example; cNickName replaces nOrder.Expected result
The index nickname is used when supplied.
- Build cSeek in the exact order of the index expression; xFilial() normally belongs in shared-table keys.
- Prefer cNickName when it is available and stable.
- Use Posicione() for a single value; explicit DbSeek() code may be clearer for traversal or several fields.
- Use GetArea() and RestArea() when the caller must retain its current work area and pointer.
- An incomplete key or a key for another index can return no value or the wrong record.
- The call moves the alias pointer.
- Assess repeated calls inside large loops; a JOIN, cache or another strategy may be more appropriate.
- The searched alias and the alias used to build the key may be different.