sp_sequence_get_range (Transact-SQL)

Статья
05/19/2015

Возвращает диапазон значений последовательности из объекта последовательности. Объект последовательности создает и выдает запрошенное количество значений, а также предоставляет приложению метаданные, связанные с диапазоном.

Дополнительные сведения о порядковых номерах см. в разделе Порядковые номера.

Значок ссылки на раздел Синтаксические обозначения в 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_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 ;

Б.Возврат всех выходных параметров

В следующем примере возвращаются выходные значения процедуры 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, выполнялся ли объект циклически и, если это так, сколько раз.

В.Пример использования ADO.NET

В следующем примере диапазон получается из Test.RangeSeq с применением ADO.NET.

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