c-treeACE V10.0 Update Guide

ctSetCurrentSequenceValue

Declaration

NINT ctSetCurrentSequenceValue(LONG seqhnd, LONG8 newval);

Description

Sets the current value for the specified sequence. If newval is outside the boundary set by the initial value (at one end) and the lower limit or upper limit (at the other end) for the sequence, ctSetCurrentSequenceValue() returns an error, and the sequence value remains unchanged.

You cannot set a sequence to the unknown value.

Improvements to Sequence API and Active Transactions

In V11.5 and later, FairCom sequence support has been improved as follows:

By default, sequence creates and deletes within an active transaction use Immediate Independent Commit Transactions (IICT) to commit immediately. If the sequence attribute ctSEQTRNDEP is specified when creating the sequence, the creation and deletion of the sequence is committed only when the transaction commits. This option makes it possible to rely upon a transaction abort to undo the sequence create or delete.
The functions that update the sequence, ctSetSequenceAttrs(), ctSetCurrentSequenceValue(), and ctGetNextSequenceValue(), commit their changes immediately if possible. If the changes cannot be immediately committed, rather than failing with error 935 (IICT_FIL), the changes commit when the transaction commits. The case where these functions cannot immediately commit is when one of these functions is called in the same transaction that created the sequence, and the sequence is using the ctSEQTRNDEP option. In that situation, an IICT cannot be used because the file has been updated in the transaction, and so the sequence record remains locked until the transaction commits or aborts.
ctSetSequenceAttrs(), ctSetCurrentSequenceValue(), and ctGetNextSequenceValue() left the sequence record locked until the transaction committed. In V11.5 and later, these functions ensure that the record is unlocked before they return (except for the case mentioned in point 2 above, where a transaction is active and IICT cannot be used).
ctCreateSequence() and ctDeleteSequence() failed with error 588 (CPND_ERR) if called within an active transaction and OPS_DEFER_CLOSE was not in effect. In V11.5 and later, we temporarily enable OPS_DEFER_CLOSE in this situation to avoid the error.

Return Values

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

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");

}