#set TITLE = "sequences"
#include top

.SH Sequences
\fBshsql\fR has a built-in convenience facility for allocating unique sequence 
numbers (serial numbers).
This may be useful in generating integer key values, or for other purposes.
In the descriptions below,
\fIidentifier\fR can be any unique identifier.  In practice it is often a table 
name that will use the resulting sequence numbers as primary key values.

#include space

.LP
Turning on sequences for a table is done using \fCCREATE SEQUENCE ON \fIidentifier\fR.
For example:
.IP
\fC$ shsql "create sequence on people"\fR
.LP

#include space

.LP
To allocate the next available sequence number, use \fCSELECT _SEQUENCE FROM \fIidentifier\fR.
For example:
.IP
\fC$ shsql "select _sequence from people"
.br
1
.br
$ \fR
.LP

#include space
.SH Notes
.LP
The \fCselect _sequence from\fR construct must be used in the simple form
as illustrated.  

.LP
Sequences are implemented by storing them in a separate table called \fC_sequences\fR.
This table is created upon the first \fCCREATE SEQUENCE\fR, and is managed using normal access
and locking conventions.  The current state of all sequences in a database can be seen
by doing \fCselect * from _sequences\fR

.LP
The next allocated value will be one greater than the value seen in the \fC_sequences\fR table.

.LP
Normally the first allocated sequence number will be 1, the second 2, and so on.
You can initialize to a desired value by issuing a command such as this
(after the sequence has been created):
.nf
	update _sequences
	 set value = \fIdesirednumber\fR
	 where tablename = '\fItablename\fR'

.LP
Resetting or backing up sequences can be done using a similar \fCUPDATE\fR command
to the above.

.LP
Other than administrative needs, the \fC_sequences\fR table shouldn't be
accessed directly by applications.


#include bottom

