Share via

  • Artículo

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).

Icono de vínculo a temasConvenciones de sintaxis de Transact-SQL

Sintaxis

        sp_cursoropen 
        cursor OUTPUT
        , 
        stmt
        
        
    [, scrollopt[ OUTPUT ] [ , ccopt[ OUTPUT ]    [ ,rowcount OUTPUT [ ,boundparam][,...n]]] ]]

Argumentos

  • 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.

    NotaNota
    >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.

Valores del código de retorno

Si no se produce ningún error, sp_cursoropen devuelve uno de los siguientes valores.

  • 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
    Está en curso una operación FETCH.

  • A
    Este cursor se ha desasignado en SQL Server y no está disponible.

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.

  • -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 AUTO_FETCH de scrollopt.

Si se usa una RPC, los valores devueltos son los siguientes.

  • 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 ha cerrado automáticamente un cursor de avance rápido.

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.

Comentarios

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.

Ejemplos

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.