cAliasCaractereObligatorio
Alias de la tabla que será consultada.
FUNCIóNPublicado
Posicione
Posicione( <cAlias>, <nOrdem>, <cSeek>, <cField>, [cNickName] ) → xRetBusca un registro por índice y retorna directamente el valor de un campo.
Descripción general
Posicione() reúne la selección de tabla, orden de índice, búsqueda de clave y lectura de campo en una sola llamada. Es útil para recuperar información relacionada sin repetir DbSelectArea(), DbSetOrder(), DbSeek() y el acceso al campo. La función cambia el área de trabajo y el puntero del alias consultado.
Sintaxis
Posicione( <cAlias>, <nOrdem>, <cSeek>, <cField>, [cNickName] ) → xRetParámetros
nOrdemNuméricoObligatorio
Número de orden del índice; se ignora con cNickName.
cSeekCaractereObligatorio
Clave montada según la expresión del índice.
cFieldCaractereObligatorio
Nombre del campo cuyo valor se devuelve.
cNickNameCaractereOpcional
Nickname opcional de índice; sustituye nOrdem.
Retorno
Retorna el contenido de cField en su tipo AdvPL. Cuando no se encuentra la clave, trata el resultado según la regla de negocio y el tipo esperado.
Nombre del cliente desde una factura
User Function ExPosicioneCliente()
Local cNombreCliente := ""
cNombreCliente := Posicione( ;
"SA1", 1, ;
xFilial("SA1") + SF2->F2_CLIENTE + SF2->F2_LOJA, ;
"A1_NOME" ;
)
MsgInfo(cNombreCliente, "Cliente")
ReturnResultado esperado
La función localiza el cliente y retorna A1_NOME.
Búsqueda de producto protegida
User Function ExPosicioneProducto()
Local aArea := GetArea()
Local cDescripcion := Posicione("SB1", 1, xFilial("SB1") + "000001", "B1_DESC")
RestArea(aArea)
MsgInfo(cDescripcion, "Producto")
ReturnResultado esperado
El área y el puntero originales se restauran después de la búsqueda.
Nickname de índice
// Consulta el ejemplo en portugués; cNickName sustituye nOrdem.Resultado esperado
Se utiliza el nickname cuando se informa.
- Monta cSeek exactamente en el orden de la expresión del índice; xFilial() suele formar parte de las claves compartidas.
- Prefiere cNickName cuando esté disponible y sea estable.
- Usa Posicione() para un valor puntual; DbSeek() explícito puede ser más claro al recorrer o leer varios campos.
- Usa GetArea() y RestArea() cuando el llamador debe conservar su área y puntero.
- Una clave incompleta o de otro índice puede devolver un valor vacío o un registro incorrecto.
- La llamada mueve el puntero del alias.
- Evalúa llamadas repetidas dentro de bucles grandes; JOIN, caché u otra estrategia puede ser mejor.
- El alias buscado puede ser distinto del alias que compone la clave.