sp_sequence_get_range (Transact-SQL)
適用於：
SQL Server Azure SQL 資料庫 Azure SQL 受控執行個體 Azure Synapse Analytics
從序列物件傳回序列值的範圍。 時序物件會產生併發出所要求的值數目，並提供應用程式與範圍相關的元數據。
如需序號的詳細資訊，請參閱 序號。
語法
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);