cSomaCaractereRequired
Character sequence to increment.
FUNCTIONPublished
Soma1
Soma1( <cSoma>, [nPos], [lSomaLow], [lCompleteSUM] ) → cRetIncrements a character sequence, combining digits and letters when needed.
Overview
Soma1() produces the next value of a text sequence. It is useful when a character field must advance without direct numeric conversion, such as short item numbers, internal codes or counters shown on screen. The sequence can move from digits to letters, so it must not be handled as an ordinary number or used in arithmetic calculations.
Syntax
Soma1( <cSoma>, [nPos], [lSomaLow], [lCompleteSUM] ) → cRetParameters
nPosNuméricoOptional
Position in the sequence to move.
lSomaLowLógicoOptional
Whether lowercase characters are used in the sequence.
lCompleteSUMLógicoOptional
Controls full use of the characters available for sequential numbering; the consulted source reports .F. as the default.
Return value
Returns a string containing the next sequence value.
Simple increment
User Function ExSoma1Simple()
Local cSequence := "100"
cSequence := Soma1(cSequence)
MsgInfo(cSequence, "Next sequence")
ReturnExpected result
The character sequence "100" becomes "101".
When the sequence reaches letters
User Function ExSoma1Alphanumeric()
Local cSequence := "9999"
cSequence := Soma1(cSequence)
MsgInfo(cSequence, "Alphanumeric sequence")
ReturnExpected result
In the reference example, "9999" becomes "999A". Validate the environment compatibility rule before using it as a business contract.
Generate and reverse a sequence
User Function ExSoma1AndTira1()
Local cSequence := "00"
Local nStep
For nStep := 1 To 150
cSequence := Soma1(cSequence)
Next nStep
cSequence := Tira1(cSequence)
MsgInfo(cSequence, "Sequence")
ReturnExpected result
The loop advances a text sequence; Tira1() steps back using the same format.
- Treat the result as an alphanumeric sequence, not as an arithmetic number.
- Community examples show "100" becoming "101", "9999" becoming "999A", and "123AB" becoming "123AC".
- The digit-to-letter transition can be affected by environment compatibility; validate the rule in the homologated environment.
- Tira1() is the complementary decrement operation for the same sequence format.
- Do not convert the result to numeric after it can contain letters.
- Do not use Soma1() as a transactional uniqueness mechanism.
- Test every optional argument across the expected transition range.
- Ensure the target field accommodates the produced format.