sp_sequence_get_range (Transact-SQL)

適用于:SQL Server (所有支援的版本) Azure SQL Database 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_sizeBigint

[ @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_countint

[ @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 (失敗)

備註

在 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)
序號