1 files changed, 56 insertions, 29 deletions
diff --git a/src/man/create_sequence.l b/src/man/create_sequence.l
index af30a0e1ebe..0a695fa6bf4 100644
--- a/src/man/create_sequence.l
+++ b/src/man/create_sequence.l
@@ -1,7 +1,7 @@
 .\" This is -*-nroff-*-
 .\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/src/man/Attic/create_sequence.l,v 1.4 1998/06/23 17:52:32 momjian Exp $
-.TH "CREATE SEQUENCE" SQL 04/01/97 PostgreSQL PostgreSQL
+.\" $Header: /cvsroot/pgsql/src/man/Attic/create_sequence.l,v 1.5 1998/07/14 01:45:25 momjian Exp $
+.TH "CREATE SEQUENCE" SQL 07/13/98 PostgreSQL PostgreSQL
 .SH NAME
 create sequence - create a new sequence number generator
 .SH SYNOPSIS
@@ -17,7 +17,7 @@ create sequence - create a new sequence number generator
 .SH DESCRIPTION
 .BR "Create sequence"
 will enter a new sequence number generator into the current data base.
-Actually, new single block
+Actually, a new single-record
 .BR table
 with name 
 .IR seqname
@@ -26,23 +26,23 @@ The generator will be
 \*(lqowned\*(rq by the user issuing the command.
 .PP
 The 
-.BR "increment"
-is optional clause. Positive value will make ascending sequence,
+.BR increment
+clause is optional. A positive value will make an ascending sequence,
 negative - descending. Default value is 1. 
 .PP
 The optional integer
 .BR minvalue
-determines the minimum value a sequence can be. Defaults are
+determines the minimum value the sequence can generate. Defaults are
 1/-2147483647 for ascending/descending sequences.
 .PP
-Use optional integer
+The optional integer
 .BR maxvalue
-to determine the maximum value for sequence. Defaults are
+determines the maximum value the sequence can generate. Defaults are
 2147483647/-1 for ascending/descending sequences.
 .PP
-The optinal
-.BR "start"
-value enables sequence to begin anywhere.  Default is 
+The optional
+.BR start
+value sets the first value to be generated.  Default is 
 .BR minvalue
 for ascending sequences and 
 .BR maxvalue
@@ -52,14 +52,12 @@ The
 .BR cache
 option enables sequence numbers to be preallocated and 
 stored in memory for faster access. The minimum value is 1 
-(i.e. - no cache) and it is default.
-.BR NOTE: 
-each backend uses own cache to store allocated numbers.
-Cached but not used in current session numbers will be lost.
+(one value will be allocated at a time, i.e., no cache)
+and that is the default.  See below for details.
 .PP
 The optional
 .BR cycle
-keyword may be used to enable sequence to continue when the 
+keyword may be used to enable the sequence to continue after the 
 .BR maxvalue/minvalue 
 has been reached by ascending/descending sequence.
 If the limit is reached, the next number generated will be 
@@ -67,27 +65,56 @@ whatever the
 .BR minvalue/maxvalue 
 is.
 .PP
-After sequence created, You may use function
+After a sequence object has been created, you may use the function
 .BR nextval
-with sequence name as argument to get new number from sequence
-specified.
-Function
+with the sequence name as argument to generate a new number from the
+specified sequence.
+.PP
+The function
 .BR currval
 ('sequence_name')
-may be used to determine number returned by last call to
+may be used to re-fetch the number returned by the last call to
 .BR nextval
-for specified sequence in current session.
+for the specified sequence in the current session.
+.BR NOTE: 
+currval will return an error if nextval has never been called for the
+given sequence in the current backend session.  Also beware that it
+does not give the last number ever allocated, only the last one allocated
+by this backend.
 .PP
+Use a query like
 .nf
-Use query like
-
-select * from <sequence_name>;
-
-to get parameters of a sequence.
+SELECT * FROM <sequence_name>;
 .fi
+to get the parameters of a sequence.  Aside from fetching the original
+parameters, you can use
+.nf
+SELECT last_value FROM <sequence_name>;
+.fi
+to obtain the last value allocated by any backend.
 .PP
-Low-level locking is used to enable multiple simultaneous calls
-to a generator.
+Low-level locking is used to ensure that multiple backends can safely use
+a sequence object concurrently.
+.PP
+.BR NOTE: 
+Unexpected results may be obtained if a cache setting greater than one
+is used for a sequence object that will be used concurrently by multiple
+backends.  Each backend will allocate "cache" successive sequence values
+during one access to the sequence object and increase the sequence
+object's last_value accordingly.  Then, the next cache-1 uses of nextval
+within that backend simply return the preallocated values without touching
+the shared object.  So, numbers allocated but not used in the current session
+will be lost.  Furthermore, although multiple backends are guaranteed to
+allocate distinct sequence values, the values may be generated out of
+sequence when all the backends are considered.  (For example, with a cache
+setting of 10, backend A might reserve values 1..10 and return nextval=1, then
+backend B might reserve values 11..20 and return nextval=11 before backend
+A has generated nextval=2.)  Thus, with a cache setting of one it is safe
+to assume that nextval values are generated sequentially; with a cache
+setting greater than one you should only assume that the nextval values
+are all distinct, not that they are generated purely sequentially.
+Also, last_value will reflect the latest value reserved by any backend,
+whether or not it has yet been returned by nextval.
 .PP
 .SH EXAMPLES
 .nf