cAliasCaractereObrigatório
Alias da tabela que será posicionada.
FUNçãOPublicado
Posicione
Posicione( <cAlias>, <nOrdem>, <cSeek>, <cField>, [cNickName] ) --> xRetPosiciona uma tabela por uma chave de índice e retorna diretamente o conteúdo do campo solicitado.
Visão geral
Posicione() pesquisa um registro em uma tabela Protheus usando uma ordem de índice e uma expressão de busca. Quando encontra a posição correspondente, retorna o conteúdo do campo informado em cField. O parâmetro opcional cNickName permite indicar o nickname da ordem de índice; quando ele é informado, a documentação oficial registra que nOrdem é desconsiderado.
Sintaxe
Posicione( <cAlias>, <nOrdem>, <cSeek>, <cField>, [cNickName] ) --> xRetParâmetros
nOrdemNuméricoObrigatório
Número da ordem de índice utilizada na pesquisa. É desconsiderado quando cNickName é informado.
cSeekCaractereObrigatório
Expressão/chave utilizada para localizar o registro na ordem escolhida.
cFieldCaractereObrigatório
Nome do campo cujo conteúdo será devolvido pela função.
cNickNameCaractereOpcional
Nickname da ordem de índice. Quando informado, substitui a seleção feita por nOrdem.
Retorno
xRet, variante. Conteúdo do campo informado em cField para o registro localizado.
Retornando o nome do cliente
User Function ExPosicione()
Local cNome := ""
// Ordem 1 de SA1: valide a expressão do índice no ambiente.
// A chave abaixo usa filial + cliente + loja a partir da nota de saída.
cNome := Posicione("SA1", 1, ;
xFilial("SA1") + SF2->F2_CLIENTE + SF2->F2_LOJA, ;
"A1_NOME")
// A1_NOME é o nome do cliente retornado pela função.
ConOut(cNome)
ReturnResultado esperado
A função posiciona SA1 pela chave informada e devolve diretamente o conteúdo de A1_NOME.
Usando cNickName
User Function ExPosicioneNick()
Local cNickName := U_MeuNickIndice()
Local cChave := U_MinhaChave()
Local xValor
// Exemplo estrutural: use somente um nickname existente no ambiente.
// Quando cNickName é informado, nOrdem é desconsiderado.
xValor := Posicione("SA1", 0, cChave, "A1_NOME", cNickName)
Return xValorResultado esperado
O exemplo demonstra a precedência de cNickName sem inventar um nickname específico de índice.
- Monte cSeek exatamente conforme a expressão da ordem de índice escolhida.
- Quando a chave da tabela inclui filial, use xFilial() de acordo com a regra da tabela.
- Use o identificador técnico real do campo em cField; não traduza nomes como A1_NOME, A1_FILIAL ou F2_CLIENTE no fonte.
- Prefira documentar no comentário qual índice está sendo usado, principalmente quando nOrdem for numérico.
- Se o código depender de um nickname de índice, confirme o nickname disponível na versão e dicionário do ambiente.
- Não trate nOrdem como parte da chave de busca: ele apenas seleciona a ordem de índice usada para interpretar cSeek.
- Não monte cSeek sem considerar todos os componentes da expressão do índice, como filial, código e loja quando aplicáveis.
- Não suponha que Posicione() retorna apenas .T. ou .F.; o retorno é o conteúdo do campo solicitado.
- Não traduza identificadores de campos no código. Em materiais EN/ES, explique o significado mantendo o nome Protheus original.
Comentários
Ainda não há comentários aprovados.
Entre com Google ou Microsoft para comentar.