sp_sequence_get_range (Transact-SQL)

Artikel
05/19/2015

Gibt einen Bereich von Sequenzwerten eines Sequenzobjekts zurück. Das Sequenzobjekt generiert die angeforderte Anzahl der Werte, gibt diese aus und stellt Metadaten bezüglich des Bereichs für die Anwendung bereit.

Weitere Informationen zu Sequenznummern finden Sie unter Sequenznummern.

Themenlink (Symbol) Transact-SQL-Syntaxkonventionen

Syntax

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

Argumente

[ @sequence_name = ] N'sequence'
Der Name des Sequenzobjekts. Das Schema ist optional. sequence_name ist nvarchar(776).
[ @range_size = ] range_size
Die Anzahl der Werte, die aus der Sequenz abgerufen werden sollen. @range_size ist bigint.
[ @range_first_value = ] range_first_value
Der Ausgabeparameter gibt den ersten Wert (Minimal- oder Maximalwert) des Sequenzobjekts zurück, mit dem der angeforderte Bereich berechnet wurde. @range_first_value entspricht sql_variant mit demselben Basistyp wie für das Sequenzobjekt, das in der Anforderung verwendet wurde.
[ @range_last_value = ] range_last_value
Der optionale Ausgabeparameter gibt den letzten Wert des angeforderten Bereichs zurück. @range_last_value entspricht sql_variant mit demselben Basistyp wie für das Sequenzobjekt, das in der Anforderung verwendet wurde.
[ @range_cycle_count = ] range_cycle_count
Der optionale Ausgabeparameter gibt die Anzahl der Durchläufe für das Sequenzobjekt zur Rückgabe des angeforderten Bereichs zurück. @range_cycle_count ist int.
[ @sequence_increment = ] sequence_increment
Der optionaler Ausgabeparameter gibt den inkrementellen Wert des Sequenzobjekts zurück, mit dem der angeforderte Bereich berechnet wird. @sequence_increment entspricht sql_variant mit demselben Basistyp wie für das Sequenzobjekt, das in der Anforderung verwendet wurde.
[ @sequence_min_value = ] sequence_min_value
Der optionale Ausgabeparameter gibt den Minimalwert des Sequenzobjekts zurück. @sequence_min_value entspricht sql_variant mit demselben Basistyp wie für das Sequenzobjekt, das in der Anforderung verwendet wurde.
[ @sequence_max_value = ] sequence_max_value
Der optionale Ausgabeparameter gibt den Maximalwert des Sequenzobjekts zurück. @sequence_max_value entspricht sql_variant mit demselben Basistyp wie für das Sequenzobjekt, das in der Anforderung verwendet wurde.

Rückgabecodewerte

0 (Erfolg) oder 1 (Fehler)

Hinweise

sp_sequence_get_range ist im sys.-Schema und kann als sys.sp_sequence_get_range verwiesen werden.

Zyklussequenzen

Falls erforderlich, durchläuft das Sequenzobjekt die entsprechende Anzahl von Zyklen, um den angeforderten Bereich zu versorgen. Die Anzahl der Zyklussequenzen wird mit dem @range\_cycle\_count-Parameter an den Aufrufer zurückgegeben.

Hinweis
Der Durchlauf des Sequenzobjekts beginnt beim Minimalwert, wenn es sich um eine aufsteigende Sequenz handelt, und beim Maximalwert, wenn es sich um eine absteigende Sequenz handelt, nicht beim Startwert des Sequenzobjekts.

Nicht-zyklische Sequenzen

Wenn die Anzahl der Werte im angeforderten Bereich größer als die Anzahl der verbleibenden Werte im Sequenzobjekt ist, kann der angeforderte Bereich nicht vom Sequenzobjekt abgezogen werden, und der folgende Fehler 11732 wird zurückgegeben:

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

Berechtigungen

Erfordert die UPDATE-Berechtigung für das Sequenzobjekt oder das Schema des Sequenzobjekts.

Beispiele

In den folgenden Beispielen wird ein Sequenzobjekt mit dem Namen Test.RangeSeq verwendet. Mit der folgenden Anweisung können Sie die Test.RangeSeq-Sequenz erstellen.

CREATE SCHEMA Test ;
GO

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

A.Abrufen eines Bereichs von Sequenzwerten

Mit der folgenden Anweisung werden vier Sequenznummern aus dem Test.RangeSeq-Sequenzobjekt abgerufen, und die erste Nummer wird an den Benutzer zurückgegeben.

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.Zurückgeben aller Ausgabeparameter

Im folgenden Beispiel werden alle Ausgabewerte von der sp_sequence_get_range-Prozedur zurückgegeben.

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 ;

Eine Änderung des @range\_size-Arguments in einen sehr großen Wert wie 75 führt dazu, dass das Sequenzobjekt Zyklen durchläuft. Überprüfen Sie das @range\_cycle\_count-Argument, um zu ermitteln, ob und in welchem Ausmaß Zyklen vom Sequenzobjekt durchlaufen wurden.

C.Beispiel für die Verwendung von ADO.NET

Im folgenden Beispiel wird ein Bereich von Test.RangeSeq mit ADO.NET abgerufen.

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);