sp_sequence_get_range (Transact-SQL)

Artículo
03/07/2014

Devuelve un intervalo de valores de secuencia de un objeto de secuencia. El objeto de secuencia genera y emite el número de valores solicitados y proporciona a la aplicación metadatos relacionados con el intervalo.

Para obtener más información acerca de los números de secuencia, vea Números de secuencia.

Se aplica a: SQL Server (desde SQL Server 2012 hasta la versión actual).

Icono de vínculo a temas Convenciones de sintaxis de Transact-SQL (Transact-SQL)

Sintaxis

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

Argumentos

[ @sequence_name = ] N'sequence'
Nombre del objeto de secuencia. El esquema es opcional. sequence_name es de tipo nvarchar(776).
[ @range_size = ] range_size
Número de valores que se van a capturar de la secuencia. @range_size es bigint.
[ @range_first_value = ] range_first_value
El parámetro de salida opcional devuelve el primer valor (mínimo o máximo) del objeto de secuencia utilizado para calcular el intervalo solicitado. @range_first_value es sql_variant con el mismo tipo base que el del objeto de secuencia utilizado en la solicitud.
[ @range_last_value = ] range_last_value
El parámetro de salida opcional devuelve el último valor del intervalo solicitado. @range_last_value es sql_variant con el mismo tipo base que el del objeto de secuencia utilizado en la solicitud.
[ @range_cycle_count = ] range_cycle_count
El parámetro de salida opcional devuelve el número de veces que se recorre el objeto de secuencia para devolver el intervalo solicitado. @range_cycle_count es int.
[ @sequence_increment = ] sequence_increment
El parámetro de salida opcional devuelve el incremento del objeto de secuencia utilizado para calcular el intervalo solicitado. @sequence_increment es sql_variant con el mismo tipo base que el del objeto de secuencia utilizado en la solicitud.
[ @sequence_min_value = ] sequence_min_value
El parámetro de salida opcional devuelve el valor mínimo del objeto de secuencia. @sequence_min_value es sql_variant con el mismo tipo base que el del objeto de secuencia utilizado en la solicitud.
[ @sequence_max_value = ] sequence_max_value
El parámetro de salida opcional devuelve el valor máximo del objeto de secuencia. @sequence_max_value es sql_variant con el mismo tipo base que el del objeto de secuencia utilizado en la solicitud.

Valores de código de retorno

0 (correcto) o 1 (error)

Comentarios

sp_sequence_get_range está en el esquema sys. y se puede hacer referencia a él como sys.sp_sequence_get_range.

Secuencias con recorrido

Si es necesario, el objeto de secuencia hará el recorrido el número adecuado de veces para atender el intervalo solicitado. El número de veces que se recorre se devuelve al autor de llamada a través del parámetro @range\_cycle\_count.

Nota

Al hacer el recorrido, un objeto de flujo se reinicia desde el valor mínimo en el caso de una secuencia ascendente y desde el valor máximo si se trata de una secuencia descendente, no desde el valor inicial del objeto de secuencia.

Secuencias sin recorrido

Si el número de valores del intervalo solicitado es mayor que los valores disponibles restantes en el objeto de secuencia, el intervalo solicitado no se deduce del objeto de secuencia y se devuelve el siguiente error 11732:

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

Permisos

Se necesita el permiso UPDATE en el objeto de secuencia o el esquema del objeto de secuencia.

Ejemplos

En los siguientes ejemplos se utiliza un objeto de secuencia denominado Test.RangeSeq. Utilice la siguiente instrucción para crear la secuencia 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.Recuperar un intervalo de valores de secuencia

La siguiente instrucción obtiene cuatro números de secuencia del objeto de secuencia Test.RangeSeq y devuelve el primero de los números al usuario.

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.Devolver todos los parámetros de salida

En el siguiente ejemplo se devuelven todos los valores de salida del procedimiento 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 ;

Cambiar el argumento @range\_size a un número grande como 75 hará que el objeto de secuencia haga un recorrido. Compruebe el argumento @range\_cycle\_count para determinar si se ha recorrido el objeto de secuencia y, en caso afirmativo, cuántas veces.

C.Ejemplo utilizando ADO.NET

En el siguiente ejemplo se obtiene un intervalo de Test.RangeSeq utilizando 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);