FUNCTIONPublished

Posicione

Posicione( <cAlias>, <nOrdem>, <cSeek>, <cField>, [cNickName] ) --> xRet

Positions a Protheus table using an index key and directly returns the requested field value.

Banco de dadosPesquisaÍndiceProtheusxFilialCampo

01 · OVERVIEW

Overview

Posicione() searches a Protheus table using an index order and a seek expression. After locating the corresponding record, it returns the content of the field specified by cField. The optional cNickName parameter selects the index order by nickname; official documentation states that nOrdem is ignored when cNickName is supplied.

02 · SYNTAX

Syntax

Posicione( <cAlias>, <nOrdem>, <cSeek>, <cField>, [cNickName] ) --> xRet

Parameters

cAlias

CharacterRequired

Alias of the table to be positioned.

nOrdem

NumericRequired

Index order number used for the search. It is ignored when cNickName is supplied.

cSeek

CharacterRequired

Expression/key used to locate the record in the selected index order.

cField

CharacterRequired

Technical field name whose value will be returned.

cNickName

CharacterOptional

Index-order nickname. When supplied, it takes precedence over nOrdem.

Return value

xRet, variant. Value of the field specified by cField for the located record.

03 · PRACTICAL EXAMPLE

Returning the customer name

User Function ExPosicione()
    Local cName := ""

    // SA1 order 1: validate the index expression in the target environment.
    // F2_CLIENTE means “Customer”, F2_LOJA means “Store”, and A1_NOME means “Name”.
    // The key below uses branch + customer + store from the sales invoice header.
    cName := Posicione("SA1", 1, ;
                      xFilial("SA1") + SF2->F2_CLIENTE + SF2->F2_LOJA, ;
                      "A1_NOME")

    // Technical field identifiers remain exactly as defined in Protheus.
    ConOut(cName)
Return

Expected result

The function positions SA1 using the supplied key and directly returns the A1_NOME field value.

04 · PRACTICAL EXAMPLE

Using cNickName

User Function ExPosicioneNick()
    Local cNickName := U_MyIndexNick()
    Local cKey      := U_MyKey()
    Local xValue

    // Structural example: use only a nickname that actually exists in the environment.
    // When cNickName is supplied, nOrdem is ignored. A1_NOME means “Name”.
    xValue := Posicione("SA1", 0, cKey, "A1_NOME", cNickName)

Return xValue

Expected result

The example demonstrates cNickName precedence without inventing a specific index nickname.

BEST PRACTICES

Build cSeek exactly according to the expression of the selected index order.
When the table key includes a branch component, use xFilial() according to the table rules.
Use the actual technical field identifier in cField; do not rename Protheus fields in source code.
Document which index is being used, especially when nOrdem is numeric.
When relying on an index nickname, validate that the nickname exists in the target release and data dictionary.

COMMON PITFALLS

Do not treat nOrdem as part of the seek key; it only selects the index order used to interpret cSeek.
Do not build cSeek without all components of the selected index expression, such as branch, code, and store when applicable.
Do not assume Posicione() returns only .T. or .F.; it returns the requested field content.
Do not translate field identifiers in code. Explain their meaning in localized documentation while preserving the original Protheus name.

Posicione

Overview

Syntax

Parameters

Return value

Returning the customer name

Using cNickName

Related content

Comments