sp_sequence_get_range (Transact-SQL)

適用於:SQL ServerAzure SQL DatabaseAzure 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_name Nvarchar(776)

[ @range_size = ] range_size 要從序列擷取的值數目。 @range_size Bigint

[ @range_first_value = ] range_first_value 輸出參數會傳回序列物件用來計算所要求範圍的第一個(最小值或最大值)值。 @range_first_value SQL_variant 與要求中使用的時序物件之基底類型相同。

[ @range_last_value = ] range_last_value 選擇性輸出參數會傳回要求範圍的最後一個值。 @range_last_value與 要求中使用的序列物件基底類型相同,SQL_variant

[ @range_cycle_count = ] range_cycle_count 選擇性輸出參數會傳回序列物件迴圈的次數,以傳回要求的範圍。 @range_cycle_count int

[ @sequence_increment = ] sequence_increment 選擇性輸出參數會傳回序列物件的遞增,用來計算要求的範圍。 @sequence_increment SQL_variant 與要求中使用的序列物件基底類型相同。

[ @sequence_min_value = ] sequence_min_value 選擇性輸出參數會傳回時序物件的最小值。 @sequence_min_value 要求中使用的序列物件相同基底類型SQL_variant。

[ @sequence_max_value = ] sequence_max_value 選擇性輸出參數會傳回序列物件的最大值。 @sequence_max_value 要求中使用的時序物件相同基底類型SQL_variant。

傳回碼值

0 (成功) 或 1 (失敗)

備註

sp_sequence_get_rangeis sys. 架構和 可以參考為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)
序號