sp_sequence_get_range (Transact-SQL)

Articolo
05/19/2015

Restituisce un intervallo di valori di sequenza da un oggetto sequenza. L'oggetto sequenza genera e pubblica il numero richiesto di valori e fornisce all'applicazione i metadati relativi all'intervallo.

Per ulteriori informazioni sui numeri di sequenza, vedere Numeri di sequenza.

Icona di collegamento a un argomento Convenzioni della sintassi Transact-SQL

Sintassi

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

Argomenti

[ @sequence_name = ] N'sequence'
Nome dell'oggetto sequenza. Lo schema è facoltativo. sequence_name è di tipo nvarchar(776).
[ @range_size = ] range_size
Numero di valori da recuperare dalla sequenza. @range_size è di tipo bigint.
[ @range_first_value = ] range_first_value
Il parametro di output restituisce il primo valore (minimo o massimo) dell'oggetto sequenza usato per calcolare l'intervallo richiesto. @range_first_value è di tipo sql_variant con lo stesso tipo di base di quello dell'oggetto sequenza utilizzato nella richiesta.
[ @range_last_value = ] range_last_value
Il parametro di output facoltativo restituisce l'ultimo valore dell'intervallo richiesto. @range_last_value è di tipo sql_variant con lo stesso tipo di base di quello dell'oggetto sequenza utilizzato nella richiesta.
[ @range_cycle_count = ] range_cycle_count
Il parametro di output facoltativo restituisce il numero di volte in cui è stato riavviato l'oggetto sequenza per la restituzione dell'intervallo richiesto. @range_cycle_count è di tipo int.
[ @sequence_increment = ] sequence_increment
Il parametro di output facoltativo restituisce l'incremento dell'oggetto sequenza utilizzato per calcolare l'intervallo richiesto. @sequence_increment è di tipo sql_variant con lo stesso tipo di base di quello dell'oggetto sequenza utilizzato nella richiesta.
[ @sequence_min_value = ] sequence_min_value
Il parametro di output facoltativo restituisce il valore minimo dell'oggetto sequenza. @sequence_min_value è di tipo sql_variant con lo stesso tipo di base di quello dell'oggetto sequenza utilizzato nella richiesta.
[ @sequence_max_value = ] sequence_max_value
Il parametro di output facoltativo restituisce il valore massimo dell'oggetto sequenza. @sequence_max_value è di tipo sql_variant con lo stesso tipo di base di quello dell'oggetto sequenza utilizzato nella richiesta.

Valori di codice restituiti

0 (esito positivo) o 1 (esito negativo)

Osservazioni

sp_sequence_get_range si trova nello schema sys. ed è possibile farvi riferimento come sys.sp_sequence_get_range.

Sequenze con riavvio

Se necessario, l'oggetto sequenza verrà riavviato il numero di volte opportuno a servire l'intervallo richiesto. Il numero di riavvii viene restituito al chiamante tramite il parametro @range\_cycle\_count.

[!NOTA]

Quando viene eseguito il ciclo, un oggetto sequenza viene riavviato dal valore minimo per una sequenza con ordine crescente e dal valore massimo per una sequenza con ordine decrescente, non dal valore iniziale dell'oggetto sequenza.

Sequenze senza riavvio

Se il numero di valori nell'intervallo richiesto è maggiore dei valori disponibili rimanenti nell'oggetto sequenza, l'intervallo richiesto non viene dedotto dall'oggetto sequenza e viene restituito l'errore 11732 seguente:

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

Autorizzazioni

È richiesta l'autorizzazione UPDATE per l'oggetto sequenza o lo schema dell'oggetto sequenza.

Esempi

Negli esempi seguenti viene utilizzato un oggetto sequenza denominato Test.RangeSeq. Utilizzare l'istruzione seguente per creare la sequenza 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.Recupero di un intervallo di valori di sequenza

L'istruzione seguente ottiene quattro numeri di sequenza dall'oggetto sequenza Test.RangeSeq è restituisce il primo numero all'utente.

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.Restituzione di tutti i parametri di output

Nell'esempio seguente vengono restituiti tutti i valori di output della procedura 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 ;

La modifica dell'argomento @range\_size in un numero maggiore, ad esempio 75, provocherà il riavvio dell'oggetto sequenza. Controllare l'argomento @range\_cycle\_count per determinare se e quante volte l'oggetto sequenza è stato riavviato.

C.Esempio con ADO.NET

Nell'esempio seguente viene ottenuto un intervallo da Test.RangeSeq utilizzando 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);