Declaration
NINT ctCreateSequence(pctSEQATTR pseqattr);Description
Creates a new sequence with the specified attributes. The following ctSEQATTR structure fields must be initialized:
- seqnam - The name of the new sequence. No sequence by that name must currently exist.
- seqini - The initial sequence value. If the sequence enforces a limit, the initial sequence value must be less than the sequence limit for an incrementing sequence or must be greater than the sequence limit for a decrementing sequence.
- seqcur - The current sequence value. For an incrementing sequence, the current sequence value must be greater than or equal to the initial sequence value, and if the sequence enforces a limit the current sequence value must be less than or equal to the limit value. For a decrementing sequence, the current sequence value must be less than or equal to the initial sequence value, and if the sequence enforces a limit the current sequence value must be greater than or equal to the sequence limit. If sequnk is set to a non-zero value, the seqcur value is ignored, and the current sequence value is set to the unknown value.
- seqinc - The sequence increment/decrement amount: It must be a positive value that is less than the difference between the initial sequence value and the sequence limit
- seqlim - The sequence limit: The sequence limit must be greater than the initial sequence value for an incrementing sequence or must be less than the initial sequence value for a decrementing sequence. The sequence limit is only enforced if the sequence type specifies the ctSEQLIM bit.
-
seqtyp - The sequence type: It must be set to one of:
- ctSEQINC (incrementing sequence)
-
ctSEQDEC (decrementing sequence)
- and either one of:
- ctSEQCYC (cycling sequence)
-
ctSEQTRM (terminating sequence)
- Optionally include ctSEQLIM (enforce sequence limit).
- sequnk - Setting the sequence unknown flag causes the initial sequence value to be set to the unknown value. Otherwise, the current sequence number is set to the initial sequence number.
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 | An invalid sequence name was specified: the name is NULL, empty, or too long. |
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