sp_cursoropen (Transact-SQL)
Se aplica a: SQL Server
Abre un cursor. sp_cursoropen
define la instrucción SQL asociada a las opciones de cursor y cursor y, a continuación, rellena el cursor. sp_cursoropen
es equivalente a la combinación de las instrucciones DECLARE_CURSOR
Transact-SQL y OPEN
. Este procedimiento se invoca especificando ID = 2
en un paquete de flujo de datos tabular (TDS).
Convenciones de sintaxis de Transact-SQL
Sintaxis
sp_cursoropen cursor OUTPUT
, stmt
[ , scrollopt [ OUTPUT ]
[ , ccopt [ OUTPUT ]
[ , rowcount OUTPUT [ , boundparam ] [ , ...n ] ] ] ]
[ ; ]
Argumentos
cursor
Un identificador del cursor generado por SQL Server. cursor es un handle
valor que se debe proporcionar en todos los procedimientos posteriores que implican el cursor, como sp_cursorfetch
. El parámetro cursor es int y no puede ser NULL
.
cursor permite que varios cursores estén activos en una única conexión de base de datos.
stmt
Parámetro necesario que define el conjunto de resultados del cursor. Cualquier cadena de consulta válida (sintaxis y enlace) de cualquier tipo de cadena (independientemente de Unicode, size, etcetera).) puede servir como un tipo de valor stmt válido.
scrollopt
Opción de desplazamiento. El parámetro scrollopt es int, con un valor predeterminado de NULL
y puede ser uno de los valores siguientes.
Valor | Descripción |
---|---|
0x0001 |
KEYSET |
0x0002 |
DYNAMIC |
0x0004 |
FORWARD_ONLY |
0x0008 |
STATIC |
0x10 |
FAST_FORWARD |
0x1000 |
PARAMETERIZED_STMT |
0x2000 |
AUTO_FETCH |
0x4000 |
AUTO_CLOSE |
0x8000 |
CHECK_ACCEPTED_TYPES |
0x10000 |
KEYSET_ACCEPTABLE |
0x20000 |
DYNAMIC_ACCEPTABLE |
0x40000 |
FORWARD_ONLY_ACCEPTABLE |
0x80000 |
STATIC_ACCEPTABLE |
0x100000 |
FAST_FORWARD_ACCEPTABLE |
Debido a la posibilidad de que el valor solicitado no sea adecuado para el cursor definido por stmt, este parámetro actúa como entrada y salida. En casos como este, SQL Server asigna un valor adecuado.
ccopt
Opción de control de simultaneidad. ccopt es un parámetro opcional que requiere uno de los siguientes valores de entrada int .
Valor | Descripción |
---|---|
0x0001 |
READ_ONLY |
0x0002 |
SCROLL_LOCKS (anteriormente conocido como LOCKCC ) |
0x0004 |
OPTIMISTIC (anteriormente conocido como OPTCC ) |
0x0008 |
OPTIMISTIC (anteriormente conocido como OPTCCVAL ) |
0x2000 |
ALLOW_DIRECT |
0x4000 |
UPDT_IN_PLACE |
0x8000 |
CHECK_ACCEPTED_OPTS |
0x10000 |
READ_ONLY_ACCEPTABLE |
0x20000 |
SCROLL_LOCKS_ACCEPTABLE |
0x40000 |
OPTIMISTIC_ACCEPTABLE |
0x80000 |
OPTIMISITC_ACCEPTABLE |
Al igual que con scrollopt, SQL Server puede invalidar los valores de ccopt solicitados.
rowcount
Número de filas de búfer de captura que se van a usar con AUTO_FETCH
. El valor predeterminado es 20 filas. rowcount se comporta de forma diferente cuando se asigna como un valor de entrada frente a un valor devuelto.
Como valor de entrada | Como valor devuelto |
---|---|
Cuando se especifica el AUTO_FETCH valor scrollopt , rowcount representa el número de filas que se van a colocar en el búfer de captura.Nota: > 0 es un valor válido cuando AUTO_FETCH se especifica, pero de lo contrario se omite. |
Representa el número de filas del conjunto de resultados, excepto cuando se especifica el valor scrolloptAUTO_FETCH . |
boundparam
Indica el uso de parámetros adicionales. boundparam es un parámetro opcional que se debe especificar si el valor scrollopt PARAMETERIZED_STMT
está establecido ON
en .
Valores de código de retorno
Si no se produce ningún error, sp_cursoropen
devuelve uno de los valores siguientes.
Valor | Descripción |
---|---|
0 |
El procedimiento se ejecutó correctamente. |
0x0001 |
Se produjo un error durante la ejecución (un error secundario, no lo suficientemente grave como para generar un error en la operación). |
0x0002 |
Está en curso una operación asincrónica. |
0x0002 |
Una FETCH operación está en proceso. |
A |
Este cursor se desasignó y no está disponible. |
Cuando se produce un error, los valores devueltos pueden ser incoherentes y no se puede garantizar la precisión.
Cuando el parámetro rowcount se especifica como un valor devuelto, se produce el siguiente conjunto de resultados.
Valor | Descripción |
---|---|
-1 |
Se devuelve si el número de filas es desconocido o no es aplicable. |
-n |
Se devuelve cuando está en vigor un rellenado asincrónico. Representa el número de filas que se colocaron en el búfer de captura cuando se especifica el valor scrolloptAUTO_FETCH . |
Si se usa una RPC, los valores devueltos son los siguientes.
Valor | Descripción |
---|---|
0 |
El procedimiento es correcto. |
1 |
Se produjo un error en el procedimiento. |
2 |
Se genera un cursor de conjunto de claves de forma asincrónica. |
16 |
Se cerró automáticamente un cursor de avance rápido. |
Si el sp_cursoropen
procedimiento se ejecuta correctamente, se envían los parámetros de devolución RPC y un conjunto de resultados con información de formato de columna TDS (0xa0
y 0xa1
mensajes). Si no puede ejecutarse se envían uno o varios mensajes de error TDS. En cualquier caso, no se devuelve ningún dato de fila y el recuento de DONE
mensajes es 0
. 0x81
se devuelve (estándar para SELECT
instrucciones) junto con los flujos de 0xa5
token y 0xa4
.
Comentarios
Parámetro stmt
Si stmt especifica la ejecución de un procedimiento almacenado, los parámetros de entrada pueden definirse como constantes como parte de la cadena stmt o especificarse como argumentos boundparam . Las variables declaradas se pueden pasar como parámetros enlazados de esta manera.
El contenido permitido del parámetro stmt depende de si el valor devuelto de ccopt ALLOW_DIRECT
estaba vinculado por OR
el resto de los valores de ccopt :
Si
ALLOW_DIRECT
no se especifica, se debe usar una instrucción Transact-SQLSELECT
oEXECUTE
una instrucción que llame a un procedimiento almacenado que contenga una solaSELECT
instrucción. Además, laSELECT
instrucción debe calificar como cursor; es decir, no puede contener las palabras claveSELECT INTO
oFOR BROWSE
.Si
ALLOW_DIRECT
se especifica , esto podría dar lugar a una o varias instrucciones Transact-SQL, incluidas las instrucciones que ejecutan otros procedimientos almacenados con varias instrucciones.SELECT
Las instrucciones que no son o cualquierSELECT
instrucción que contiene las palabras claveSELECT INTO
oFOR BROWSE
se ejecutan, y no dan lugar a la creación de un cursor. Lo mismo sucede con cualquierSELECT
instrucción incluida en un lote de varias instrucciones. En los casos en los que unaSELECT
instrucción contiene cláusulas que solo pertenecen a cursores, se omiten esas cláusulas. Por ejemplo, cuando el valor de ccopt es0x2002
, se trata de una solicitud para:Cursor con bloqueos de desplazamiento, si solo hay una sola
SELECT
instrucción que se califica como cursor oEjecución de instrucciones directas si hay varias instrucciones, una sola
SELECT
instrucción que no es o unaSELECT
instrucción que no califica como cursor.
Parámetro scrollopt
Los cinco primeros valores scrollopt (KEYSEY
, DYNAMIC
, FORWARD_ONLY
, STATIC
y FAST_FORWARD
) son mutuamente excluyentes.
PARAMETERIZED_STMT
y CHECK_ACCEPTED_TYPES
se pueden vincular mediante OR
cualquiera de los cinco primeros valores.
AUTO_FETCH
y AUTO_CLOSE
se pueden vincular mediante OR
a FAST_FORWARD
.
Si CHECK_ACCEPTED_TYPES
es ON
, al menos uno de los cinco últimos valores scrollopt (KEYSET_ACCEPTABLE
, DYNAMIC_ACCEPTABLE
, FORWARD_ONLY_ACCEPTABLE
, STATIC_ACCEPTABLE
o FAST_FORWARD_ACCEPTABLE
) también debe ser ON
.
STATIC
los cursores siempre se abren como READ_ONLY
. Esto significa que la tabla subyacente no se puede actualizar a través de este cursor.
Parámetro ccopt
Los cuatro primeros valores de ccopt (READ_ONLY
, SCROLL_LOCKS
y ambos OPTIMISTIC
valores) son mutuamente excluyentes.
Nota:
Elegir uno de los cuatro primeros valores de ccopt determina si el cursor es de solo lectura o si se usan métodos de bloqueo o optimistas para evitar actualizaciones perdidas. Si no se especifica un valor ccopt , el valor predeterminado es OPTIMISTIC
.
ALLOW_DIRECT
y CHECK_ACCEPTED_TYPES
se pueden vincular mediante OR
cualquiera de los cuatro primeros valores.
UPDT_IN_PLACE
se puede vincular mediante OR
, READ_ONLY
SCROLL_LOCKS
o cualquiera de los OPTIMISTIC
valores.
Si CHECK_ACCEPTED_TYPES
es ON
, al menos uno de los cuatro últimos valores de ccopt (READ_ONLY_ACCEPTABLE
, SCROLL_LOCKS_ACCEPTABLE
y cualquiera de los OPTIMISTIC_ACCEPTABLE
valores) también debe ser ON.
Las funciones y DELETE
posicionadas UPDATE
solo se pueden realizar dentro del búfer de captura y solo si el valor de ccopt es igual SCROLL_LOCKS
o OPTIMISTIC
. Si SCROLL_LOCKS
es el valor especificado, se garantiza que la operación se realice correctamente. Si OPTIMISTIC
es el valor especificado, se produce un error en la operación si la fila cambió desde que se capturó por última vez.
El motivo de este error es que, cuando OPTIMISTIC
es el valor especificado, se realiza una función de control de moneda optimista comparando marcas de tiempo o valores de suma de comprobación, según lo determinado por SQL Server. Si alguna de estas filas no coincide, se produce un error en la operación.
Al especificar UPDT_IN_PLACE
como valor devuelto, se rigen los siguientes resultados:
Si no se establece al realizar una actualización posicionada en una tabla con un índice único, el cursor elimina la fila de su tabla de trabajo e la inserta al final de cualquiera de las columnas de clave usadas por el cursor, que cambia esas columnas.
Si se establece
ON
, el cursor actualiza las columnas de clave en la fila original de la tabla de trabajo.
Parámetro bound_param
El nombre del parámetro debe ser paramdef cuando PARAMETERIZED_STMT
se especifica, según el mensaje de error en el código. Cuando PARAMETERIZED_STMT
no se especifica, no se especifica ningún nombre en el mensaje de error.
Consideraciones sobre RPC
La marca de entrada RPC RETURN_METADATA
se puede establecer en 0x0001
para solicitar que se devuelvan los metadatos de la lista de selección de cursor en el flujo de TDS.
Ejemplos
A Parámetro bound_param
Cualquier parámetro después del quinto se pasa como parámetro de entrada al plan de instrucción. El primer parámetro de este tipo debe ser una cadena de la siguiente forma:
<parameter_name> <data_type> [ ,... n ]
Los parámetros posteriores se usan para pasar los valores que se van a sustituir por en <parameter_name>
la instrucción .