sp_sequence_get_range (Transact-SQL)

  • 發行項

適用於：SQL ServerAzure SQL DatabaseAzure 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);

相關內容