sp_sequence_get_range (Transact-SQL)

适用于:SQL ServerAzure SQL 数据库Azure SQL 托管实例Azure Synapse Analytics

从序列对象中返回一系列序列值。 序列对象生成和发出请求的值数目,并为应用程序提供与该系列序列值相关的元数据。

有关序列号的详细信息,请参阅 序列号

Transact-SQL 语法约定

语法

  
sp_sequence_get_range [ @sequence_name = ] N'<sequence>'   
     , [ @range_size = ] range_size  
     , [ @range_first_value = ] range_first_value OUTPUT   
    [, [ @range_last_value = ] range_last_value OUTPUT ]  
    [, [ @range_cycle_count = ] range_cycle_count OUTPUT ]  
    [, [ @sequence_increment = ] sequence_increment OUTPUT ]  
    [, [ @sequence_min_value = ] sequence_min_value OUTPUT ]  
    [, [ @sequence_max_value = ] sequence_max_value OUTPUT ]  
    [ ; ]  

参数

[ @sequence_name = ] N'sequence' 序列对象的名称。 架构是可选的。 sequence_namenvarchar (776)

[ @range_size = ] range_size 要从序列中提取的值数。 @range_size很大

[ @range_first_value = ] range_first_value 输出参数返回用于计算所请求范围的序列对象的第一个 (最小值或最大) 值。 @range_first_valuesql_variant与 请求中使用的序列对象的基类型相同。

[ @range_last_value = ] range_last_value 可选输出参数返回所请求范围的最后一个值。 @range_last_valuesql_variant与 请求中使用的序列对象的基类型相同。

[ @range_cycle_count = ] range_cycle_count 可选输出参数返回序列对象为了返回所请求范围而循环的次数。 @range_cycle_countint

[ @sequence_increment = ] sequence_increment 可选输出参数返回用于计算所请求范围的序列对象的增量。 @sequence_incrementsql_variant与 请求中使用的序列对象的基类型相同。

[ @sequence_min_value = ] sequence_min_value 可选输出参数返回序列对象的最小值。 @sequence_min_valuesql_variant与 请求中使用的序列对象的基类型相同。

[ @sequence_max_value = ] sequence_max_value 可选输出参数返回序列对象的最大值。 @sequence_max_valuesql_variant与 请求中使用的序列对象的基类型相同。

返回代码值

0(成功)或 1(失败)

备注

sys 中的sp_sequence_get_rangeis。 架构 和 可以作为sys.sp_sequence_get_range引用。

循环序列

如果需要,序列对象将循环相应的次数以处理请求的范围。 将通过 @range_cycle_count 参数向调用方返回循环次数。

注意

在进行循环时,序列对象从序列对象最小值(升序)或最大值(降序)重新开始,而不是从序列对象的开始值重新开始。

非循环序列

如果请求的范围中的值数目大于序列对象中的剩余可用值数目,并不会从序列对象中缩减请求的范围,将返回下面的错误 11732:

The requested range for sequence object '%.*ls' exceeds the maximum or minimum limit. Retry with a smaller range.

权限

要求对序列对象或序列对象架构具有 UPDATE 权限。

示例

以下示例使用名为 Test.RangeSeq 的序列对象。 使用以下语句创建 Test.RangeSeq 序列。

CREATE SCHEMA Test ;  
GO  
  
CREATE SEQUENCE Test.RangeSeq  
    AS int   
    START WITH 1  
    INCREMENT BY 1  
    MINVALUE 1  
    MAXVALUE 25  
    CYCLE  
    CACHE 10  
;  

A. 检索序列值的范围

以下语句从 Test.RangeSeq 序列对象获取四个序列号,并将第一个序列号返回给用户。

DECLARE @range_first_value_output sql_variant ;  
  
EXEC sys.sp_sequence_get_range  
@sequence_name = N'Test.RangeSeq'  
, @range_size = 4  
, @range_first_value = @range_first_value_output OUTPUT ;  
  
SELECT @range_first_value_output AS FirstNumber ;  
  

B. 返回所有输出参数

以下示例返回sp_sequence_get_range过程的所有输出值。

DECLARE    
  @FirstSeqNum sql_variant  
, @LastSeqNum sql_variant  
, @CycleCount int  
, @SeqIncr sql_variant  
, @SeqMinVal sql_variant  
, @SeqMaxVal sql_variant ;  
  
EXEC sys.sp_sequence_get_range  
@sequence_name = N'Test.RangeSeq'  
, @range_size = 5  
, @range_first_value = @FirstSeqNum OUTPUT   
, @range_last_value = @LastSeqNum OUTPUT   
, @range_cycle_count = @CycleCount OUTPUT  
, @sequence_increment = @SeqIncr OUTPUT  
, @sequence_min_value = @SeqMinVal OUTPUT  
, @sequence_max_value = @SeqMaxVal OUTPUT ;  
  
-- The following statement returns the output values  
SELECT  
  @FirstSeqNum AS FirstVal  
, @LastSeqNum AS LastVal  
, @CycleCount AS CycleCount  
, @SeqIncr AS SeqIncrement  
, @SeqMinVal AS MinSeq  
, @SeqMaxVal AS MaxSeq ;  
  

@range_size 参数更改为较大的数字(例如 75)将导致循环访问序列对象。 请检查 @range_cycle_count 参数以确定是否循环访问序列对象以及循环次数。

C. 使用 ADO.NET 的示例

以下示例使用 ADO.NET 从 Test.RangeSeq 获取范围。

SqlCommand cmd = new SqlCommand();  
cmd.Connection = conn;  
cmd.CommandType = CommandType.StoredProcedure;  
cmd.CommandText = "sys.sp_sequence_get_range";  
cmd.Parameters.AddWithValue("@sequence_name", "Test.RangeSeq");  
cmd.Parameters.AddWithValue("@range_size", 10);  
  
// Specify an output parameter to retrieve the first value of the generated range.  
SqlParameter firstValueInRange = new SqlParameter("@range_first_value", SqlDbType.Variant);  
firstValueInRange.Direction = ParameterDirection.Output;  
cmd.Parameters.Add(firstValueInRange);  
  
conn.Open();  
cmd.ExecuteNonQuery();  
  
// Output the first value of the generated range.  
Console.WriteLine(firstValueInRange.Value);  
  

另请参阅

CREATE SEQUENCE (Transact-SQL)
ALTER SEQUENCE (Transact-SQL)
DROP SEQUENCE (Transact-SQL)
NEXT VALUE FOR (Transact-SQL)
序列号