Compartir a través de

sp_cursoropen (Transact-SQL)

  • Artículo

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, etc.) 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 NULLy 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 ONen .

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-SQL SELECT o EXECUTE una instrucción que llame a un procedimiento almacenado que contenga una sola SELECT instrucción. Además, la SELECT instrucción debe calificar como cursor; es decir, no puede contener las palabras clave SELECT INTO o FOR 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 cualquier SELECT instrucción que contiene las palabras clave SELECT INTO o FOR BROWSE se ejecutan, y no dan lugar a la creación de un cursor. Lo mismo sucede con cualquier SELECT instrucción incluida en un lote de varias instrucciones. En los casos en los que una SELECT instrucción contiene cláusulas que solo pertenecen a cursores, se omiten esas cláusulas. Por ejemplo, cuando el valor de ccopt es 0x2002, se trata de una solicitud para:

    • Cursor con bloqueos de desplazamiento, si solo hay una sola SELECT instrucción que se califica como cursor o

    • Ejecución de instrucciones directas si hay varias instrucciones, una solaSELECT instrucción que no es o una SELECT instrucción que no califica como cursor.

Parámetro scrollopt

Los cinco primeros valores scrollopt (KEYSEY, DYNAMIC, FORWARD_ONLY, STATICy 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_ACCEPTABLEo 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_LOCKSy 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_PLACEse puede vincular mediante OR , READ_ONLYSCROLL_LOCKSo 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_ACCEPTABLEy 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 .

Contenido relacionado