sp_sequence_get_range (Transact-SQL)
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);