sp_sequence_get_range (Transact-SQL)

Si applica a: SQL Server database SQL di Azure Istanza gestita di SQL di Azure Azure Synapse Analytics

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 altre informazioni sui numeri di sequenza, vedere Numeri di sequenza.

Convenzioni relative alla sintassi Transact-SQL

Sintassi

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

Argomenti

[ @sequence_name = ] N'sequence_name'

Nome dell'oggetto sequenza. Lo schema è facoltativo. @sequence_name è nvarchar(776), senza impostazione predefinita.

[ @range_size = ] range_size

Numero di valori da recuperare dalla sequenza. @range_size è bigint, senza impostazione predefinita.

[ @range_first_value = ] range_first_value OUTPUT

Il parametro di output restituisce il primo valore (minimo o massimo) dell'oggetto sequenza usato per calcolare l'intervallo richiesto. @range_first_value è un parametro OUTPUT di tipo sql_variant, con lo stesso tipo di base dell'oggetto sequenza usato nella richiesta.

[ @range_last_value = ] range_last_value OUTPUT

Il parametro di output facoltativo restituisce l'ultimo valore dell'intervallo richiesto. @range_last_value è un parametro OUTPUT di tipo sql_variant, con lo stesso tipo di base dell'oggetto sequenza usato nella richiesta.

[ @range_cycle_count = ] range_cycle_count OUTPUT

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 è un parametro OUTPUT di tipo int.

[ @sequence_increment = ] sequence_increment OUTPUT

Il parametro di output facoltativo restituisce l'incremento dell'oggetto sequenza utilizzato per calcolare l'intervallo richiesto. @sequence_increment è un parametro OUTPUT di tipo sql_variant, con lo stesso tipo di base dell'oggetto sequenza usato nella richiesta.

[ @sequence_min_value = ] sequence_min_value OUTPUT

Il parametro di output facoltativo restituisce il valore minimo dell'oggetto sequenza. @sequence_min_value è un parametro OUTPUT di tipo sql_variant, con lo stesso tipo di base dell'oggetto sequenza usato nella richiesta.

[ @sequence_max_value = ] sequence_max_value OUTPUT

Il parametro di output facoltativo restituisce il valore massimo dell'oggetto sequenza. @sequence_max_value è un parametro OUTPUT di tipo sql_variant, con lo stesso tipo di base dell'oggetto sequenza usato nella richiesta.

Valori del codice restituito

0 (esito positivo) o 1 (errore).

Osservazioni:

sp_sequence_get_rangeè nello sys schema e può essere fatto riferimento a .sys.sp_sequence_get_range

Sequenze con riavvio

Se necessario, l'oggetto sequenza esegue il ciclo del numero appropriato di volte per il servizio dell'intervallo richiesto. Il numero di volte in cui viene eseguito il ciclo 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:

L'intervallo richiesto per l'oggetto sequenza '%.*ls' supera il limite massimo o minimo. Riprovare con un intervallo più piccolo.

Autorizzazioni

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

Esempi

Negli esempi seguenti viene usato un oggetto sequenza denominato Test.RangeSeq. Usare l'istruzione seguente per creare la Test.RangeSeq sequenza.

CREATE SCHEMA Test;
GO

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

R. Recuperare un intervallo di valori di sequenza

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

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

Nell'esempio seguente vengono restituiti tutti i valori di output della sp_sequence_get_range routine.

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;

Se si modifica l'argomento @range_size in un numero elevato, ad 75 esempio l'oggetto sequenza viene ciclizzato. Controllare l'argomento @range_cycle_count per determinare se e quante volte è stato eseguito il ciclo dell'oggetto sequenza.

C. Esempio con ADO.NET

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