sp_sequence_get_range (Transact-SQL)
Se aplica a:
SQL ServerAzure SQL Database Azure SQL Instancia administrada Azure Synapse Analytics
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 sobre los números de secuencia, vea Números de secuencia.
Convenciones de sintaxis de Transact-SQL
Sintaxis
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 ]
[ ; ]
Argumentos
[ @sequence_name = ] N'sequence_name'
Nombre del objeto de secuencia. El esquema es opcional. @sequence_name es nvarchar(776), sin ningún valor predeterminado.
[ @range_size = ] range_size
Número de valores que se van a capturar de la secuencia. @range_size es bigint, sin valor predeterminado.
[ @range_first_value = ] range_first_value OUTPUT
El parámetro de salida devuelve el primer valor (mínimo o máximo) del objeto de secuencia que se usa para calcular el intervalo solicitado. @range_first_value es un parámetro OUTPUT de tipo sql_variant, con el mismo tipo base que el objeto de secuencia usado en la solicitud.
[ @range_last_value = ] range_last_value OUTPUT
El parámetro de salida opcional devuelve el último valor del intervalo solicitado. @range_last_value es un parámetro OUTPUT de tipo sql_variant, con el mismo tipo base que el objeto de secuencia usado en la solicitud.
[ @range_cycle_count = ] range_cycle_count OUTPUT
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 un parámetro OUTPUT de tipo int.
[ @sequence_increment = ] sequence_increment OUTPUT
El parámetro de salida opcional devuelve el incremento del objeto de secuencia utilizado para calcular el intervalo solicitado. @sequence_increment es un parámetro OUTPUT de tipo sql_variant, con el mismo tipo base que el objeto de secuencia usado en la solicitud.
[ @sequence_min_value = ] sequence_min_value OUTPUT
El parámetro de salida opcional devuelve el valor mínimo del objeto de secuencia. @sequence_min_value es un parámetro OUTPUT de tipo sql_variant, con el mismo tipo base que el objeto de secuencia usado en la solicitud.
[ @sequence_max_value = ] sequence_max_value OUTPUT
El parámetro de salida opcional devuelve el valor máximo del objeto de secuencia. @sequence_max_value es un parámetro OUTPUT de tipo sql_variant, con el mismo tipo base que el objeto de secuencia usado en la solicitud.
Valores de código de retorno
0 (correcto) o 1 (erróneo).
Comentarios
sp_sequence_get_range está en el sys esquema y se puede hacer referencia a como sys.sp_sequence_get_range.
Secuencias con recorrido
Si es necesario, el objeto de secuencia recorre el número adecuado de veces para atender el intervalo solicitado. El número de veces que se recorre el ciclo se devuelve al autor de la 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:
El intervalo solicitado para el objeto de secuencia '%.*ls' supera el límite máximo o mínimo. Vuelva a intentarlo con un intervalo menor.
Permisos
Requiere UPDATE permiso en el objeto de secuencia o en el esquema del objeto de secuencia.
Ejemplos
En los ejemplos siguientes se usa un objeto de secuencia denominado Test.RangeSeq. Use la siguiente instrucción para crear la Test.RangeSeq secuencia.
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 instrucción siguiente 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_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. Devolver todos los parámetros de salida
En el ejemplo siguiente se devuelven todos los valores de salida del sp_sequence_get_range procedimiento.
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 gran número, como 75 , por ejemplo, hace que el objeto de secuencia se produzca un ciclo. Compruebe el argumento @range_cycle_count para determinar si y cuántas veces ha ciclo el objeto de secuencia.
C. Ejemplo utilizando ADO.NET
En el ejemplo siguiente se obtiene un intervalo de Test.RangeSeq mediante 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);