sp_sequence_get_range (Transact-SQL)

  • 项目

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

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

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

Transact-SQL 语法约定

语法

sp_sequence_get_range
    [ @sequence_name = ] N'sequence_name'
    , [ @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_name'

序列对象的名称。 架构是可选的。 @sequence_name 为 nvarchar（776），没有默认值。

[ @range_size = ] range_size

要从序列中提取的值数目。 @range_size为 bigint，没有默认值。

[ @range_first_value = ] range_first_value OUTPUT

一个输出参数，它返回序列对象的第一个（最小或最大）值以用于计算请求的范围。 @range_first_value是sql_variant类型的 OUTPUT 参数，其基类型与请求中使用的序列对象相同。

[ @range_last_value = ] range_last_value OUTPUT

一个可选的输出参数，它返回请求的范围中的最后一个值。 @range_last_value是sql_variant类型的 OUTPUT 参数，其基类型与请求中使用的序列对象相同。

[ @range_cycle_count = ] range_cycle_count OUTPUT

一个可选的输出参数，它返回为了返回所请求的范围而需要循环访问序列对象的次数。 @range_cycle_count是 int 类型的 OUTPUT 参数。

[ @sequence_increment = ] sequence_increment OUTPUT

一个可选的输出参数，它返回序列对象的增量以用于计算请求的范围。 @sequence_increment是sql_variant类型的 OUTPUT 参数，其基类型与请求中使用的序列对象相同。

[ @sequence_min_value = ] sequence_min_value OUTPUT

一个可选的输出参数，它返回序列对象的最小值。 @sequence_min_value是sql_variant类型的 OUTPUT 参数，其基类型与请求中使用的序列对象相同。

[ @sequence_max_value = ] sequence_max_value OUTPUT

一个可选的输出参数，它返回序列对象的最大值。 @sequence_max_value是sql_variant类型的 OUTPUT 参数，其基类型与请求中使用的序列对象相同。

返回代码值

0（成功）或 1（失败）。

注解

sp_sequence_get_range 在架构中 sys ，可以引用为 sys.sp_sequence_get_range.

循环序列

如有必要，序列对象会周期相应的次数来为请求的范围提供服务。 循环到调用方通过 @range_cycle_count 参数的次数。

注意

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

非循环序列

如果请求范围中的值数大于序列对象中剩余的可用值，则请求的范围不会从序列对象中扣除，并返回以下错误 11732：

序列对象 '%.*ls' 的请求范围超出了最大或最小限制。 使用较小的范围重试。

权限

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);

相关内容