sp_sequence_get_range (Transact-SQL)

  • Artigo

Aplica-se a: SQL ServerBanco de Dados SQL do Azure Instância Gerenciada de SQL do Azure Azure Synapse Analytics

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.

Convenções de sintaxe de Transact-SQL

Sintaxe

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

Argumentos

@sequence_name [ = ] N'sequence_name'

O nome do objeto de sequência. O esquema é opcional. @sequence_name é nvarchar(776), sem padrão.

@range_size [ = ] range_size

O número de valores a ser buscado da sequência. @range_size é bigint, sem padrão.

@range_first_value [ = ] range_first_value SAÍDA

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 é um parâmetro OUTPUT do tipo sql_variant, com o mesmo tipo base que o objeto de sequência usado na solicitação.

@range_last_value [ = ] range_last_value SAÍDA

O parâmetro de saída opcional retorna o último valor do intervalo solicitado. @range_last_value é um parâmetro OUTPUT do tipo sql_variant, com o mesmo tipo base que o objeto de sequência usado na solicitação.

@range_cycle_count [ = ] range_cycle_count SAÍDA

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 é um parâmetro OUTPUT do tipo int.

@sequence_increment [ = ] sequence_increment SAÍDA

O parâmetro de saída opcional retorna o incremento do objeto de sequência usado para calcular o intervalo solicitado. @sequence_increment é um parâmetro OUTPUT do tipo sql_variant, com o mesmo tipo base que o objeto de sequência usado na solicitação.

@sequence_min_value [ = ] sequence_min_value SAÍDA

O parâmetro de saída opcional retorna o valor mínimo do objeto de sequência. @sequence_min_value é um parâmetro OUTPUT do tipo sql_variant, com o mesmo tipo base que o objeto de sequência usado na solicitação.

@sequence_max_value [ = ] sequence_max_value SAÍDA

O parâmetro de saída opcional retorna o valor máximo do objeto de sequência. @sequence_max_value é um parâmetro OUTPUT do tipo sql_variant, com o mesmo tipo base que o objeto de sequência usado na solicitação.

Valores do código de retorno

0 (sucesso) ou 1 (falha).

Comentários

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

Sequências de ciclo

Se necessário, o objeto de sequência alterna o número apropriado de vezes para atender ao intervalo solicitado. O número de vezes que o ciclo é retornado ao chamador por meio do 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 do 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 seguinte erro 11732 será retornado:

O intervalo solicitado para o objeto de sequência '%.*ls' excede o limite máximo ou mínimo. Tente novamente com um intervalo menor.

Permissões

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

Exemplos

Os exemplos a seguir usam um objeto de sequência chamado Test.RangeSeq. Use a instrução a seguir para criar a Test.RangeSeq sequência.

CREATE SCHEMA Test;
GO

CREATE SEQUENCE Test.RangeSeq AS INT START
    WITH 1
    INCREMENT BY 1
    MINVALUE 1
    MAXVALUE 25
    CYCLE CACHE 10;

R. Recuperar 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 dos números para o usuário.

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

O exemplo a seguir retorna todos os valores de saída do sp_sequence_get_range procedimento.

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 faz com que o objeto de sequência alterne. Verifique o argumento @range_cycle_count para determinar se e quantas vezes o objeto de sequência foi alternado.

C. Exemplo: usando ADO.NET

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

Conteúdo relacionado