cAliasCaractereObrigatório
Alias da tabela em que a pesquisa será realizada.
FUNçãOPublicado
Posicione
Posicione( <cAlias>, <nOrdem>, <cSeek>, <cField>, [cNickName] ) → xRetBusca um registro por índice e retorna diretamente o conteúdo de um campo.
Visão geral
Posicione() combina a seleção de uma tabela, a definição da ordem, a busca de uma chave e a leitura de um campo em uma única chamada. É útil para recuperar uma informação relacionada sem escrever a sequência DbSelectArea(), DbSetOrder(), DbSeek() e acesso ao campo a cada uso. A função altera a área de trabalho e o ponteiro do alias consultado; portanto, use-a conscientemente em rotinas que trabalham com mais de uma tabela.
Sintaxe
Posicione( <cAlias>, <nOrdem>, <cSeek>, <cField>, [cNickName] ) → xRetParâmetros
nOrdemNuméricoObrigatório
Número da ordem de índice a ser usada. É desconsiderado quando cNickName é informado.
cSeekCaractereObrigatório
Chave de busca montada conforme a expressão do índice selecionado.
cFieldCaractereObrigatório
Nome do campo cujo valor será retornado.
cNickNameCaractereOpcional
Nickname da ordem de índice. Quando informado, substitui a escolha por nOrdem.
Retorno
Retorna o conteúdo do campo informado em cField, em seu tipo AdvPL. Quando a chave não é localizada, trate o retorno de acordo com a regra de negócio e com o tipo esperado do campo.
Nome do cliente a partir de uma nota fiscal
User Function ExPosicioneCliente()
Local cNomeCliente := ""
// Índice 1 de SA1: A1_FILIAL + A1_COD + A1_LOJA
cNomeCliente := Posicione( ;
"SA1", ;
1, ;
xFilial("SA1") + SF2->F2_CLIENTE + SF2->F2_LOJA, ;
"A1_NOME" ;
)
MsgInfo(cNomeCliente, "Cliente")
ReturnResultado esperado
A função procura o cliente de SF2 na ordem informada e devolve o valor de A1_NOME.
Consulta protegida com GetArea() e RestArea()
User Function ExPosicioneProduto()
Local aArea := GetArea()
Local cDescricao := ""
// Índice 1 de SB1: B1_FILIAL + B1_COD
cDescricao := Posicione( ;
"SB1", ;
1, ;
xFilial("SB1") + "000001", ;
"B1_DESC" ;
)
RestArea(aArea)
MsgInfo(cDescricao, "Produto")
ReturnResultado esperado
A busca posiciona SB1 temporariamente. RestArea() restaura a área e o ponteiro existentes antes da consulta.
Uso de nickname de índice
User Function ExPosicionePorNick()
Local cNome := ""
cNome := Posicione( ;
"SA1", ;
0, ;
xFilial("SA1") + "000001" + "01", ;
"A1_NOME", ;
"A1_FILIAL+A1_COD+A1_LOJA" ;
)
ConOut(cNome)
ReturnResultado esperado
Quando o nickname é informado, a função utiliza essa identificação da ordem e ignora nOrdem.
- Monte cSeek exatamente na mesma ordem da expressão do índice: em tabelas compartilhadas, a filial normalmente faz parte da chave e deve ser obtida com xFilial().
- Prefira cNickName quando ele estiver disponível e for estável no ambiente; ele deixa a intenção da busca mais clara e evita depender apenas da posição numérica do índice.
- Posicione() é adequada para recuperar um valor pontual. Para percorrer registros, validar existência com comportamento específico ou manipular vários campos, a sequência explícita com DbSeek() pode ser mais legível.
- Preserve a área anterior com GetArea() e RestArea() quando a rotina não puder deixar o alias consultado como área corrente ou alterar seu ponteiro para o chamador.
- Não use uma chave incompleta ou montada para outra ordem de índice: o resultado pode ser vazio ou apontar para um registro diferente do esperado.
- A consulta move o ponteiro do alias. Em rotinas de browse, relatórios e loops, não presumir que a posição anterior continuará disponível depois da chamada.
- Não use Posicione() repetidamente dentro de grandes loops sem avaliar o custo. Em cenários de volume, uma query com JOIN, cache local ou outra estratégia pode ser mais apropriada.
- Não confunda o alias da tabela pesquisada com o alias que fornece os valores para compor a chave. Eles podem ser diferentes, como no exemplo de faturamento e clientes.