sp_sequence_get_range (Transact-SQL)

Article
05/19/2015

Retourne une plage de valeurs de séquence d'un objet séquence. L'objet séquence génère et émet le nombre de valeurs demandées et fournit l'application avec les métadonnées relatives à la plage.

Pour plus d'informations sur les numéros de séquence, consultez Numéros de séquence.

Icône Lien de rubrique Conventions de la syntaxe Transact-SQL

Syntaxe

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

Arguments

[ @sequence_name = ] N'sequence'
Nom de l'objet séquence. Le schéma est facultatif. sequence_name a la valeur nvarchar(776).
[ @range_size = ] range_size
Nombre de valeurs à extraire de la séquence. @range_size est de type bigint.
[ @range_first_value = ] range_first_value
Le paramètre de sortie retourne la première valeur (minimale ou maximale) de l'objet séquence utilisée pour calculer la plage demandée. @range_first_value est de type sql_variant avec le même type de base que celui de l'objet séquence utilisé dans la demande.
[ @range_last_value = ] range_last_value
Le paramètre de sortie facultatif retourne la dernière valeur de la plage demandée. @range_last_value est de type sql_variant avec le même type de base que celui de l'objet séquence utilisé dans la demande.
[ @range_cycle_count = ] range_cycle_count
Le paramètre de sortie facultatif retourne le nombre de fois où l'objet séquence a été répété pour retourner la plage demandée. @range_cycle_count est de type int.
[ @sequence_increment = ] sequence_increment
Le paramètre de sortie facultatif retourne l'incrément de l'objet séquence utilisé pour calculer la plage demandée. @sequence_increment est de type sql_variant avec le même type de base que celui de l'objet séquence utilisé dans la demande.
[ @sequence_min_value = ] sequence_min_value
Le paramètre de sortie facultatif retourne la valeur minimale de l'objet séquence. @sequence_min_value est de type sql_variant avec le même type de base que celui de l'objet séquence utilisé dans la demande.
[ @sequence_max_value = ] sequence_max_value
Le paramètre de sortie facultatif retourne la valeur maximale de l'objet séquence. @sequence_max_value est de type sql_variant avec le même type de base que celui de l'objet séquence utilisé dans la demande.

Valeurs des codes de retour

0 (réussite) ou 1 (échec)

Notes

sp_sequence_get_range figure dans le schéma sys. et peut être référencé comme sys.sp_sequence_get_range.

Séquences se répétant

Si nécessaire, l'objet séquence se répétera le nombre de fois approprié afin de fournir la plage demandée. Le nombre de répétitions est retourné à l'appelant via le paramètre @range\_cycle\_count.

[!REMARQUE]

Lors d'un cycle, un objet séquence redémarre à la valeur minimale dans le cas d'une séquence croissante et à la valeur maximale pour une séquence décroissante, et non pas à la valeur de début de l'objet séquence.

Séquences ne se répétant pas

Si le nombre de valeurs dans la plage demandée est supérieur aux valeurs disponibles restantes dans l'objet séquence, la plage demandée n'est pas déduite de l'objet séquence et l'erreur suivante 11732 est retournée :

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

Autorisations

Requiert l'autorisation UPDATE sur l'objet séquence ou le schéma de l'objet séquence.

Exemples

Les exemples suivants utilisent un objet séquence nommé Test.RangeSeq. Utilisez l'instruction suivante pour créer la séquence 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.Récupération d'une plage de valeurs de séquence

L'instruction suivante obtient quatre numéros séquentiels de l'objet séquence Test.RangeSeq et retourne le premier des nombres à l'utilisateur.

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.Retour de tous les paramètres de sortie

L'exemple suivant retourne toutes les valeurs de sortie de la procédure 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 modification de l'argument @range\_size en nombre plus grand, comme 75, provoque l'exécution répétée de l'objet séquence. Vérifiez l'argument @range\_cycle\_count pour déterminer si et combien de fois l'objet séquence a été répété.

C.Exemple utilisant ADO.NET

L'exemple suivant obtient une plage de Test.RangeSeq en utilisant 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);