sp_sequence_get_range (Transact-SQL)

發行項
03/07/2014

從順序物件傳回順序值的範圍。順序物件會產生及發出要求的值數目，並將範圍相關的中繼資料提供給應用程式。

如需有關序號的詳細資訊，請參閱＜序號＞。

適用於：SQL Server (SQL Server 2012 至目前版本)。

語法

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_range 位於 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 sql_variant , 
        @range_first_value_output sql_variant ;

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