KI_SET_SERIAL
| Argument | Enumeration | Purpose |
|---|---|---|
| handle | Handle | |
| value | New serial number | |
| offset | Offset of serial column | |
| nCache | Sequence cache size | |
| status | KDB_ERROR_ENUM | Return status |
KI_SET_SERIAL
This routine resets the value of the serial for a table open on a handle. This value is the one returned by a call to KI_GET_SERIAL.
For KDB type 6 native tables only, this routine can also be used to set an offset in the row which can used for an auto-incrementing key segment. If the offset value is non-zero then auto-incrementing mode is in effect for the table and each call to KI_WRITE for the table will have the current value of the serial inserted into the row at that specified offset (counted from 1, minimum offset is 2 and max is the total row length-3) and the serial incremented. The column defined by the offset must be a 4 byte unsigned binary integer.
If autoincrementing mode is in effect then KI_GET_SERIAL will give an error KE_BADFUNCTION as the modes should not be mixed. KI_SET_SERIAL will give an error KE_BADFUNCTION if the offset is out of the allowed range of 2 to reclen-3.
For KDB type 7 tables and for Oracle tables the serial number is associated with a special column specified by name as SERIAL A in the CREATE TABLE SQL. Autoincrementing is always enabled by default for such tables however setting an offset of zero will disable autoincrementing for that column while the table is open on that handle. Setting a non-zero offset value allows autoincrementing using the value supplied as the next number to be used. You might want to disable autoincrementing this way if you are copying or repairing a table.
For Oracle partitioned tables the SERIAL A serial number is associated with the base table and is the same sequence for all partitions. However with KDB each partition has its own sequence. To get a separate sequence for each partition with Oracle you should specify SERIAL P rather than SERIAL A in the CREATE TABLE. All partitions must be created consistently.
Oracle will cache serial numbers in memory on the database server to improve performance. This means that if a transaction rolls back, or is deadlocked and is repeated, then a serial number can be skipped. If the database server crashes then all the unused cached serials will be lost. Hence these serials cannot be used in cases where all numbers must be accounted for and you ought to use a counter in a table so that they can be allocated transactionally. The size of the cache can be controlled by the nCache argument. If zero a default of 50 will be assumed.