Product Documentation

FairCom ISAM for C

Previous Topic

Next Topic

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 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

TOCIndex