cSomaCaractereObrigatório
Sequência de caracteres que será incrementada.
FUNçãOPublicado
Soma1
Soma1( <cSoma>, [nPos], [lSomaLow], [lCompleteSUM] ) → cRetIncrementa uma sequência armazenada em caractere, combinando dígitos e letras quando necessário.
Visão geral
Soma1() cria o próximo valor de uma sequência textual. É útil quando um campo de caractere precisa avançar sem depender de conversão numérica direta — por exemplo, em numerações curtas de itens, códigos internos ou contadores apresentados em tela. A sequência pode avançar de valores numéricos para letras; por isso, não deve ser tratada como um número comum nem usada para cálculos aritméticos.
Sintaxe
Soma1( <cSoma>, [nPos], [lSomaLow], [lCompleteSUM] ) → cRetParâmetros
nPosNuméricoOpcional
Posição da sequência a ser movimentada.
lSomaLowLógicoOpcional
Indica o uso de caracteres minúsculos na sequência.
lCompleteSUMLógicoOpcional
Controla o uso completo dos caracteres disponíveis na numeração sequencial; a fonte consultada informa .F. como padrão.
Retorno
Retorna uma string com o próximo valor da sequência, preservando a natureza caractere do resultado.
Incremento simples
User Function ExSoma1Simples()
Local cSequencia := "100"
cSequencia := Soma1(cSequencia)
MsgInfo(cSequencia, "Próxima sequência")
ReturnResultado esperado
A sequência caractere "100" passa a "101".
Quando a sequência alcança letras
User Function ExSoma1Alfanumerico()
Local cSequencia := "9999"
cSequencia := Soma1(cSequencia)
MsgInfo(cSequencia, "Sequência alfanumérica")
ReturnResultado esperado
No exemplo de referência, "9999" avança para "999A". Valide a regra de compatibilidade do ambiente antes de adotá-la como contrato de negócio.
Gerar e desfazer uma sequência
User Function ExSoma1ETira1()
Local cSequencia := "00"
Local nPasso
For nPasso := 1 To 150
cSequencia := Soma1(cSequencia)
Next nPasso
// Tira1() retorna ao valor anterior no mesmo formato.
cSequencia := Tira1(cSequencia)
MsgInfo(cSequencia, "Sequência")
ReturnResultado esperado
O laço demonstra o avanço de uma sequência textual; Tira1() permite retornar um passo no mesmo padrão.
- Soma1() trabalha com uma convenção de sequência alfanumérica. O resultado não representa necessariamente um valor que possa ser somado, ordenado ou comparado como número.
- Em exemplos difundidos pela comunidade, "100" avança para "101", "9999" pode avançar para "999A" e "123AB" para "123AC".
- O comportamento de transição entre dígitos e letras pode ser influenciado por compatibilidade do ambiente. A documentação comunitária cita MV_SOMAOLD: confirme a regra no ambiente homologado antes de persistir códigos gerados.
- Tira1() é a operação complementar de decremento para sequências no mesmo formato.
- Não converta o retorno para numérico: após a transição para letras, Val() e cálculos comuns deixam de representar a sequência corretamente.
- Não use Soma1() para garantir unicidade transacional. Para numeração fiscal, chaves técnicas ou concorrência, utilize os mecanismos próprios do Protheus e do banco de dados.
- Não altere nPos, lSomaLow ou lCompleteSUM sem testar a sequência completa esperada, inclusive a passagem de 9 para letras.
- Mantenha o tamanho e o formato do campo de destino compatíveis com os valores que podem ser produzidos.