sp_sequence_get_range (Transact-SQL)sp_sequence_get_range (Transact-SQL)

APLICA-SE A: simSQL Server simBanco de Dados SQL do Azure simAzure Synapse Analytics (SQL DW) nãoParallel Data Warehouse APPLIES TO: yesSQL Server yesAzure SQL Database yesAzure Synapse Analytics (SQL DW) noParallel Data Warehouse

Retorna um intervalo de valores de sequência de um objeto de sequência.Returns a range of sequence values from a sequence object. O objeto de sequência gera e emite o número de valores solicitado e fornece o aplicativo com metadados relacionados ao intervalo.The sequence object generates and issues the number of values requested and provides the application with metadata related to the range.

Para obter mais informações sobre números de sequência, consulte números de sequência.For a more information about sequence numbers, see Sequence Numbers.

Ícone de link do tópico Convenções de sintaxe Transact-SQLTopic link icon Transact-SQL Syntax Conventions

SintaxeSyntax

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

ArgumentosArguments

[ @sequence_name = ] N'sequence' o nome do objeto de sequência.[ @sequence_name = ] N'sequence' The name of the sequence object. O esquema é opcional.The schema is optional. sequence_name é nvarchar (776) .sequence_name is nvarchar(776).

[ @range_size = ] range_size o número de valores a serem obtidos da sequência.[ @range_size = ] range_size The number of values to fetch from the sequence. @range_size é bigint.@range_size is bigint.

[ @range_first_value = ] range_first_value 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 = ] range_first_value Output parameter returns the first (minimum or maximum) value of the sequence object used to calculate the requested range. @range_first_value é sql_variant com o mesmo tipo base do objeto de sequência usado na solicitação.@range_first_value is sql_variant with the same base type as that of the sequence object used in the request.

[ @range_last_value = ] range_last_value parâmetro de saída opcional retorna o último valor do intervalo solicitado.[ @range_last_value = ] range_last_value Optional output parameter returns the last value of the requested range. @range_last_value é sql_variant com o mesmo tipo base do objeto de sequência usado na solicitação.@range_last_value is sql_variant with the same base type as that of the sequence object used in the request.

[ @range_cycle_count = ] range_cycle_count parâmetro de saída opcional retorna o número de vezes que o objeto de sequência foi reciclado para retornar o intervalo solicitado.[ @range_cycle_count = ] range_cycle_count Optional output parameter returns the number of times that the sequence object cycled in order to return the requested range. @range_cycle_count é int.@range_cycle_count is int.

[ @sequence_increment = ] sequence_increment parâmetro de saída opcional retorna o incremento do objeto de sequência usado para calcular o intervalo solicitado.[ @sequence_increment = ] sequence_increment Optional output parameter returns the increment of the sequence object used to calculate the requested range. @sequence_increment é sql_variant com o mesmo tipo base do objeto de sequência usado na solicitação.@sequence_increment is sql_variant with the same base type as that of the sequence object used in the request.

[ @sequence_min_value = ] sequence_min_value parâmetro de saída opcional retorna o valor mínimo do objeto de sequência.[ @sequence_min_value = ] sequence_min_value Optional output parameter returns the minimum value of the sequence object. @sequence_min_value é sql_variant com o mesmo tipo base do objeto de sequência usado na solicitação.@sequence_min_value is sql_variant with the same base type as that of the sequence object used in the request.

[ @sequence_max_value = ] sequence_max_value parâmetro de saída opcional retorna o valor máximo do objeto de sequência.[ @sequence_max_value = ] sequence_max_value Optional output parameter returns the maximum value of the sequence object. @sequence_max_value é sql_variant com o mesmo tipo base do objeto de sequência usado na solicitação.@sequence_max_value is sql_variant with the same base type as that of the sequence object used in the request.

Valores do código de retornoReturn Code Values

0 (êxito) ou 1 (falha)0 (success) or 1 (failure)

RemarksRemarks

sp_sequence_get_rangeis no sys.sp_sequence_get_rangeis in the sys. Schema e pode ser referenciado como sys. sp_sequence_get_range.schema and can be referenced as sys.sp_sequence_get_range.

Sequências de cicloCycling sequences

Se preciso for, o objeto de sequência vai realizar um ciclo do número apropriado de vezes para atender ao intervalo solicitado.If required, the sequence object will cycle the appropriate number of times to service the requested range. O número de vezes em que o ciclo é retornado para o chamador pelo parâmetro @range_cycle_count.The number of times cycled is returned to the caller through the @range_cycle_count parameter.

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.When cycling, a sequence object restarts from the minimum value for an ascending sequence and the maximum value for a descending sequence, not from the start value of the sequence object.

Sequências não cíclicasNon-cycling sequences

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:If the number of values in the requested range is greater than the remaining available values in the sequence object the requested range is not deducted from the sequence object and the following error 11732 is returned:

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

PermissõesPermissions

Requer permissão UPDATE no objeto de sequência ou o esquema do objeto de sequência.Requires UPDATE permission on the sequence object or the schema of the sequence object.

ExemplosExamples

Os exemplos a seguir usam um objeto Sequence chamado Test. RangeSeq.The following examples use a sequence object named Test.RangeSeq. Use a instrução a seguir para criar a sequência test. RangeSeq.Use the following statement to create the Test.RangeSeq sequence.

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

A.A. Recuperando um intervalo de valores de sequênciaRetrieving a range of sequence values

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.The following statement gets four sequence numbers from the Test.RangeSeq sequence object and returns the first of the numbers to the user.

DECLARE @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.B. Retornando todos os parâmetros de saídaReturning all output parameters

O exemplo a seguir retorna todos os valores de saída do procedimento sp_sequence_get_range.The following example returns all the output values from the sp_sequence_get_range procedure.

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.Changing the @range_size argument to a large number such as 75 will cause the sequence object to cycle. Verifique o argumento @range_cycle_count para determinar se e quantas vezes o objeto de sequência realizou o ciclo.Check the @range_cycle_count argument to determine if and how many times the sequence object has cycled.

C.C. Exemplo: usando ADO.NETExample using ADO.NET

O exemplo a seguir obtém um intervalo do Test. RangeSeq usando ADO.NET.The following example gets a range from the Test.RangeSeq by using 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);  
  

Consulte tambémSee Also

CREATE SEQUENCE (Transact-SQL) CREATE SEQUENCE (Transact-SQL)
ALTER SEQUENCE (Transact-SQL) ALTER SEQUENCE (Transact-SQL)
DROP SEQUENCE (Transact-SQL) DROP SEQUENCE (Transact-SQL)
NEXT VALUE FOR (Transact-SQL) NEXT VALUE FOR (Transact-SQL)
Números de sequênciaSequence Numbers