sp_sequence_get_range (Transact-SQL)

Artigo
05/19/2015

Retorna um intervalo de valores de sequência de um objeto de sequência. O objeto de sequência gera e emite o número de valores solicitado e fornece o aplicativo com metadados relacionados ao intervalo.

Para obter mais informações sobre números de sequência, consulte Números de sequência.

Ícone de vínculo de tópico Convenções de sintaxe Transact-SQL

Sintaxe

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 ]
    [ ; ]

Argumentos

[ @sequence_name = ] N'sequence'
O nome do objeto de sequência. O esquema é opcional. sequence_name é nvarchar(776).
[ @range_size = ] range_size
O número de valores a ser buscado da sequência. @range_size é bigint.
[ @range_first_value = ] range_first_value
O parâmetro de saída retorna o primeiro valor (mínimo ou máximo) do objeto de sequência usado para calcular o intervalo solicitado. @range_first_value é sql_variant com o mesmo tipo base que o objeto de sequência usado na solicitação.
[ @range_last_value = ] range_last_value
O parâmetro de saída opcional retorna o último valor do intervalo solicitado. @range_last_value is sql_variant com o mesmo tipo base que o objeto de sequência usado na solicitação.
[ @range_cycle_count = ] range_cycle_count
O parâmetro de saída opcional retorna o número de vezes que o objeto de sequência realizou um ciclo a fim de retornar o intervalo solicitado. @range_cycle_count é int.
[ @sequence_increment = ] sequence_increment
O parâmetro de saída opcional retorna o incremento do objeto de sequência usado para calcular o intervalo solicitado. @sequence_increment é sql_variant com o mesmo tipo base que o objeto de sequência usado na solicitação.
[ @sequence_min_value = ] sequence_min_value
O parâmetro de saída opcional retorna o valor mínimo do objeto de sequência. @sequence_min_value é sql_variant com o mesmo tipo base que o objeto de sequência usado na solicitação.
[ @sequence_max_value = ] sequence_max_value
O parâmetro de saída opcional retorna o valor máximo do objeto de sequência. @sequence_max_value é sql_variant com o mesmo tipo base que o objeto de sequência usado na solicitação.

Valores de código de retorno

0 (êxito) ou 1 (falha)

Comentários

sp_sequence_get_range está no esquema sys. e pode ser referenciado como sys.sp_sequence_get_range.

Sequências de ciclo

Se preciso for, o objeto de sequência vai realizar um ciclo do número apropriado de vezes para atender ao intervalo solicitado. O número de vezes em que o ciclo é retornado para o chamador pelo parâmetro @range\_cycle\_count.

Observação
Ao realizar o ciclo, um objeto de sequência reinicia a partir do valor mínimo para uma sequência ascendente e do valor máximo para uma sequência decrescente, não a partir do valor inicial do objeto de sequência.

Sequências não cíclicas

Se o número de valores no intervalo solicitado for maior que os valores disponíveis restantes no objeto de sequência, o intervalo solicitado não será deduzido do objeto de sequência e o erro 11732 a seguir será retornado:

The requested range for sequence object '%.*ls' exceeds the maximum or minimum limit. Retry with a smaller range.

Permissões

Requer permissão UPDATE no objeto de sequência ou o esquema do objeto de sequência.

Exemplos

Os exemplos a seguir usam um objeto de sequência chamado Test.RangeSeq. Use a seguinte instrução para criar a sequência 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.Recuperando um intervalo de valores de sequência

A instrução a seguir obtém quatro números de sequência do objeto de sequência Test.RangeSeq e retorna o primeiro número ao usuário.

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.Retornando todos os parâmetros de saída

O exemplo a seguir retorna todos os valores de saída do procedimento 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 ;

Alterar o argumento @range\_size para um número grande como 75 fará o objeto de sequência realizar um ciclo. Verifique o argumento @range\_cycle\_count para determinar se e quantas vezes o objeto de sequência realizou o ciclo.

C.Exemplo: usando ADO.NET

O exemplo a seguir obtém um intervalo do Test.RangeSeq usando o 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);