c-treeACE V10.0 Update Guide

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

Value	Symbolic Constant	Value	Explanation
0	NO_ERROR	0	Successfully created the sequence.
900	SEQDUP_ERR	900	A sequence having the specified name already exists.
903	SEQTYP_ERR	903	The specified sequence type contains an invalid combination of sequence type options.
904	SEQINI_ERR	904	The initial value specified for the sequence is out of range.
905	SEQCUR_ERR	905	The current value specified for the sequence is out of range.
906	SEQLIM_ERR	906	The limit value specified for the sequence is out of range.
907	SEQINC_ERR	907	The increment value specified for the sequence is out of range.
901	SEQNAM_ERR	901	Invalid sequence name specified (NULL, empty, or too long).
902	SEQHND_ERR	902	Invalid sequence handle.

See c-treeACE 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");

}