ctGetNextSequenceValue

Declaration

NINT ctGetNextSequenceValue(LONG seqhnd, pLONG8 pnxtval, pNINT punkval);

Description

Reads the next value for the specified sequence. The next value of a sequence can be one of the following:

• The next value, which is computed from the current sequence value and the attributes of the sequence set in ctCreateSeqence() or ctSetSequenceAttrs().
• The unknown value if the sequence has exceeded its minimum or maximum and is not cycling (see "Reaching the End of a Terminating Sequence" below).

Sequence values are stored in the database in which they are defined, and persist between each call to the ctSetCurrentSequenceValue() or ctGetNextSequenceValue() function.

The value of a sequence set by the ctGetNextSequenceValue() function persists in the database until the next call to ctSetCurrentSequenceValue() or ctGetNextSequenceValue() for the sequence, or until the sequence is deleted from the database.

Reaching the End of a Terminating Sequence

If the sequence is a terminating sequence, and ctGetNextSequenceValue() attempts to increment the sequence beyond its upper limit (for positive increments) or decrement the sequence beyond its lower limit (for negative increments), the function returns the unknown value and leaves the current sequence value unchanged.

Once a sequence terminates, ctGetNextSequenceValue() continues to return the unknown value for the specified sequence until it is reset to a new value with the ctSetCurrentSequenceValue() function, or its definition is changed to a cycling sequence by the ctSetSequenceAttrs() function.

After changing the sequence definition to cycle, the first use of ctGetNextSequenceValue() for the sequence sets and returns its initial value.

Return Values

See FairCom DB Error Codes for a complete listing of valid error values.

Example

ctSEQATTR seqattr;
NINT rc;
/*
** Create an incrementing sequence that starts with 1, increments by 3, and
** terminates with 100.
*/
strcpy(seqattr.seqnam, "MyFirstSequence");
seqattr.seqini = 1;
seqattr.seqinc = 3;
seqattr.seqlim = 100;
seqattr.seqtyp = ctSEQINC | ctSEQTRM | ctSEQLIM;

if ((rc = ctCreateSequence(&seqattr))) {
printf("Error: Failed to create the sequence: %d\n", rc);
} else {
printf("Successfully created the sequence.\n");
}

See also

ctCreateSequence, ctDeleteSequence, ctOpenSequence, ctCloseSequence, ctGetSequenceAttrs, ctSetSequenceAttrs, ctGetCurrentSequenceValue, ctSetCurrentSequenceValue, ctGetNextSequenceValue