Returns the next INT64 value of a static sequence, incremented
by the positive or negative value defined in the Data Dictionary.
Syntax
NEXT-VALUE ( sequence [ , logical-dbname ] [ , tenant-id ] )
|
-
sequence
- An identifier that specifies the name of a sequence defined
in the Data Dictionary.
-
logical-dbname
- 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.
tenant-id
An
integer expression that evaluates to the tenant ID of a regular tenant,
including the default tenant (0). This option applies
only to a multi-tenant sequence specified by sequence and
is intended for access primarily by a super-tenant user.
If
you are a regular-tenant user and you specify tenant-id,
the specified tenant must be the same as the tenant associated with
the database connection identity for logical-dbname or
the AVM raises a run-time error.
If you are a super-tenant
user and you do not specify tenant-id, the function
assumes the effective tenant ID (GET-EFFECTIVE-TENANT-ID function).
If the sequence specified by sequence is non-multi-tenant
(a shared sequence in a multi-tenant database), and you specify tenant-id,
the option is ignored.
Example
The
following trigger procedure uses the NextItemNum sequence to set
the ItemNum 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).
|
Notes
- 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.
- If sequence is a multi-tenant sequence in
the database, each regular tenant has their own current value of
the sequence. So, the same values are returned for each tenant that
invokes this function. If the sequence is shared in a multi-tenant
database, the values returned by this function are unique across
all tenants in the database.
Caution:
Be very careful
using multi-tenant sequences when you are updating shared tables
or multi-tenant tables for a tenant group. For more information,
see the sections on using multi-tenant-enabled sequences in OpenEdge
Development: Programming Interfaces.
- 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 compile 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.
