NEXT-VALUE function

Returns the next INT64 value of a static sequence, incremented by the positive or negative value defined in the Data Dictionary.

NEXT-VALUE ( `sequence` [ , `logical-dbname` ] )

An identifier that specifies the name of a sequence defined in the Data Dictionary.

An identifier that specifies the logical name of the database in which the sequence is defined. The database must be connected. If multiple databases are connected, you can omit this parameter if you specify a sequence that is unique to one of the databases.

The following trigger procedure uses the NextItemNum sequence to set the iItemNum field for a new Item record:

r-critem.p
TRIGGER PROCEDURE FOR Create OF Item. /* Automatically assign a unique item number using NextItemNum seq / ASSIGN Item.ItemNum = NEXT-VALUE(NextItemNum).*

If sequence is a cycling sequence, and the NEXT-VALUE function increments the sequence beyond its upper limit (for positive increments) or decrements the sequence beyond its lower limit (for negative increments), the function sets and returns the initial value defined for the sequence.

If sequence is a terminating sequence, and the NEXT-VALUE function attempts to increment the sequence beyond its upper limit (for positive increments) or decrement the sequence beyond its lower limit (for negative increments), the function returns the Unknown value (?) and leaves the current sequence value unchanged. Once a sequence terminates, NEXT-VALUE continues to return the Unknown value (?) for the specified sequence until it is reset to a new value with the CURRENT-VALUE statement, or its definition is changed to a cycling sequence. After changing the sequence definition to cycle, the first use of NEXT-VALUE for the sequence sets and returns its initial value.

The value of a sequence set by the NEXT-VALUE function persists in the database until the next CURRENT-VALUE statement or NEXT-VALUE function is invoked for the sequence, or until the sequence is deleted from the database.

You cannot invoke the NEXT-VALUE function from within a WHERE clause. Doing so generates a compiler error because the value returned by the NEXT-VALUE function can result in ambiguous expressions. To use a result from the NEXT-VALUE function in a WHERE clause, assign the result to a variable and use the variable in the WHERE clause instead.

You can use any combination of the NEXT-VALUE function, CURRENT-VALUE function, CURRENT-VALUE statement, and their dynamic versions. Use the dynamic version when you don’t know what the database name or sequence name is at run time.

Be careful when accessing a database sequence with an alias that points to a different database than the one used when the alias was defined. If you supply an alias name to the CURRENT-VALUE function or the NEXT-VALUE function, only the database used to define the alias is referenced. In this case, it is preferable to use the DYNAMIC-CURRENT-VALUE function and DYNAMIC-NEXT-VALUE function instead of the CURRENT-VALUE function and NEXT-VALUE function, respectively.