.png)
sp_cursoropen (Transact-SQL)
Abre un cursor. sp_cursoropen define la instrucción SQL asociada a las opciones de cursor y al cursor, y a continuación lo rellena. sp_cursoropen es equivalente a la combinación de las instrucciones DECLARE_CURSOR y OPEN de Transact-SQL. Este procedimiento se invoca especificando el identificador 2 en un paquete de flujo de datos tabular (TDS).
Convenciones de sintaxis de Transact-SQL
- cursor
Identificador de cursor generado por SQL Server. El parámetro cursor es un valor de identificador que se debe proporcionar en todos los procedimientos subsiguientes que impliquen al cursor, como sp_cursorfetch. El parámetro cursor es un parámetro necesario con un valor devuelto int.
El parámetro cursor permite que varios cursores estén activos en una sola conexión a bases de datos.
- stmt
Es un parámetro necesario que define el conjunto de resultados del cursor. Cualquier cadena de consulta válida (sintaxis y enlace) de un tipo de cadena (independiente de Unicode, del tamaño, etc.) puede actuar como un tipo de valor stmt válido.
- scrollopt
Opción de desplazamiento. El parámetro scrollopt es un parámetro opcional que requiere uno de los siguientes valores de entrada int.
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 a través de stmt, este parámetro actúa tanto de entrada como de 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 (conocido anteriormente como LOCKCC)
0x0004
OPTIMISTIC (conocido anteriormente como OPTCC)
0x0008
OPTIMISTIC (conocido anteriormente 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
A igual que con scrollopt, SQL Server puede invalidar los valores de ccopt solicitados.
- rowcount
Número de filas del búfer de captura que se usan con AUTO_FETCH. El valor predeterminado es 20 filas. rowcount se comporta de manera diferente cuando se asigna como un valor de entrada contra un valor devuelto.
Como valor de entrada
Como valor devuelto
Cuando se especifica el valor de scrollopt AUTO_FETCH; 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 se especifica AUTO_FETCH, de lo contrario se omite.Representa el número de filas en el conjunto de resultados, excepto cuando se especifica el valor AUTO_FETCH de scrollopt.
- boundparam
Indica el uso de parámetros adicionales. El parámetro boundparam es un parámetro opcional que se debe especificar si el valor PARAMETERIZED_STMT del parámetro scrollopt se establece en ON.
Si no se produce ningún error, sp_cursoropen devuelve uno de los siguientes valores.
Cuando se produce un error, los valores devueltos pueden ser incoherentes y no se puede garantizar la exactitud.
Cuando el parámetro rowcount se especifica como un valor devuelto, se produce el siguiente conjunto de resultados.
Si se usa una RPC, los valores devueltos son los siguientes.
| Nota |
|---|
Si el procedimiento sp_cursoropen se ejecuta correctamente, la RPC devuelve los parámetros y se envía un conjunto de resultados con información de formato de columna de TDS (mensajes 0xa0 y 0xa1). Si no puede ejecutarse se envían uno o varios mensajes de error TDS. En cualquier caso, no se devolverán los datos de ninguna fila y el contador de mensajes terminados será igual a cero. Si usa una versión de SQL Server anterior a la 7.0, se devuelven 0xa0, 0xa1 (estándar de las instrucciones SELECT) junto con las flujos de token 0xa5 y 0xa4. Si usa SQL Server 7.0, se devuelve 0x81 (estándar para las instrucciones SELECT) junto con las flujos de token 0xa5 y 0xa4. |
Parámetro stmt
Si stmt especifica la ejecución de un procedimiento almacenado, los parámetros de entrada pueden, o bien definirse como constantes como parte de la cadena stmt, o bien 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 se ha vinculado o no el valor devuelto ALLOW_DIRECT de ccopt mediante OR al resto de los valores de ccopt, es decir:
Si no se especifica ALLOW_DIRECT, se debe usar una llamada a una instrucción de Transact-SQL SELECT o EXECUTE para un procedimiento almacenado que contenga una sola instrucción SELECT. Además, la instrucción SELECT debe calificarse como un cursor; es decir, no puede contener las palabras clave SELECT INTO, FOR BROWSE ni COMPUTE.
Si se especifica ALLOW_DIRECT, esto puede dar como resultado una o más instrucciones de Transact-SQL, incluso aquellas que, a su vez, ejecuten otros procedimientos almacenados con varias instrucciones. Las instrucciones que no sean SELECT o cualquier instrucción SELECT que contenga las palabras clave SELECT INTO, FOR BROWSE o COMPUTE simplemente se ejecutarán y no darán como resultado la creación de un cursor. Lo mismo puede decirse de cualquier instrucción SELECT incluida en un lote de varias instrucciones. En los casos en los que una instrucción SELECT contenga cláusulas que solo sean relativas a los cursores, dichas cláusulas se omiten. Por ejemplo, cuando el valor de ccopt es 0x2002, esta es una solicitud para:
Un cursor con bloqueos de desplazamiento, si solo hay una instrucción SELECT que se califica como un cursor, o
La ejecución de una instrucción directa si hay varias instrucciones, una sola instrucción distinta de SELECT o una instrucción SELECT que no se califica como un cursor.
Parámetro scrollopt
Los primeros cinco valores de scrollopt (KEYSEY, DYNAMIC, FORWARD_ONLY, STATIC y FAST_FORWARD) son mutuamente excluyentes.
PARAMETERIZED_STMT y CHECK_ACCEPTED_TYPES se pueden vincular mediante OR a cualquiera de los primeros cinco 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 últimos cinco valores de scrollopt (KEYSET_ACCEPTABLE, DYNAMIC_ACCEPTABLE, FORWARD_ONLY_ACCEPTABLE, STATIC_ACCEPTABLE o FAST_FORWARD_ACCEPTABLE) también debe ser ON.
Los cursores STATIC se abren siempre como READ_ONLY. Esto significa que la tabla subyacente no se puede actualizar a través de este cursor.
Parámetro ccopt
Los primeros cuatro valores de ccopt (READ_ONLY, SCROLL_LOCKS y ambos valores OPTIMISTIC) son mutuamente excluyentes.
| Nota |
|---|
Al elegir uno de los primeros cuatro valores de ccopt, se determina si el cursor es de solo lectura o si se usan métodos optimistas o de bloqueo para evitar la pérdida de actualizaciones. Si ccopt no tiene especificado un valor, el valor predeterminado es OPTIMISTIC. |
ALLOW_DIRECT y CHECK_ACCEPTED_TYPES se pueden vincular mediante OR a cualquiera de los primeros cuatro valores.
UPDT_IN_PLACE se puede vincular mediante OR a READ_ONLY, SCROLL_LOCKS o a cualquiera de los valores OPTIMISTIC.
Si CHECK_ACCEPTED_TYPES es ON, al menos uno de los últimos cuatro valores de ccopt (READ_ONLY_ACCEPTABLE, SCROLL_LOCKS_ACCEPTABLE y cualquiera de los valores OPTIMISTIC_ACCEPTABLE) también debe ser ON.
Las funciones UPDATE y DELETE colocadas solo se pueden realizar dentro del búfer de captura y únicamente si el valor de ccopt es igual a SCROLL_LOCKS u OPTIMISTIC. Si SCROLL_LOCKS es el valor especificado, se garantiza que la operación se realiza correctamente. Si el valor especificado es OPTIMISTIC, se producirá un error en la operación si la fila ha cambiado desde que se capturó en último lugar.
La razón de este error es que cuando el valor especificado es OPTIMISTIC, una función de control de simultaneidad optimista se realiza comparando las marcas de tiempo o los valores de las sumas de comprobación, según determina SQL Server. Si alguna de estas filas no coincide, se producirá un error en la operación.
Especificar UPDT_IN_PLACE como valor devuelto produce los siguientes resultados:
Si no está establecido al realizar una actualización colocada en una tabla con un único índice, el cursor elimina la fila de su tabla de trabajo y la inserta al final de alguna de las columnas de clave que usa el cursor, con lo que las cambia.
Si está establecida en ON, el cursor simplemente actualizará las columnas de clave en la fila original de la tabla de trabajo.
Parámetro bound_param
El nombre de parámetro debería ser paramdef cuando se especifica PARAMETERIZED_STMT, según el mensaje de error del código. Cuando no se especifica PARAMETERIZED_STMT, no se especifica ningún nombre en el mensaje de error.
Consideraciones sobre RPC
La marca de entrada RPC RETURN_METADATA puede establecerse en 0x0001 para solicitar que se devuelvan los metadatos de la lista de selección del cursor en el flujo de TDS.
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 debe ser una cadena con el formato:
{ local variable name data type } [,…n]
Los parámetros subsiguientes se utilizan para pasar los valores que se van a sustituir para el parámetro local variable name en la instrucción.
