sp_cursorfetch (Transact-SQL)

Captura un búfer de una o varias filas de la base de datos. El grupo de filas de este búfer se denomina búfer de captura del cursor. sp_cursorfetch se invoca especificando el identificador 7 en un paquete de flujo TDS.

Convenciones de sintaxis de Transact-SQL

Sintaxis

sp_cursorfetch cursor 
    [ , fetchtype [ , rownum [ , nrows ] ] ] 

Argumentos

• cursor
  Es un valor de controlador generado por SQL Server y devuelto por sp_cursoropen. El parámetro cursor es un parámetro necesario que requiere un valor de entrada int. Para obtener más información, vea la sección Comentarios más adelante en este tema.

• fetchtype
  Especifica qué búfer de cursor se va a capturar. fetchtype es un parámetro opcional que requiere uno de los siguientes valores de entrada enteros.

  Valor	Nombre	Descripción
  0x0001	FIRST	Captura el primer búfer de filas nrows. Si nrows es igual a 0, el cursor se coloca antes del conjunto de resultados y no se devuelve ninguna fila.
  0x0002	NEXT	Captura el siguiente búfer de filas nrows.
  0x0004	PREV	Captura el anterior búfer de filas nrows. [!NOTA]    Al utilizar PREV para un cursor FORWARD_ONLY, se devuelve un mensaje de error porque FORWARD_ONLY solo permite el desplazamiento en una dirección.
  0x0008	LAST	Captura el último búfer de filas nrows. Si nrows es igual a 0, el cursor se coloca después del conjunto de resultados y no se devuelve ninguna fila. [!NOTA]    Al utilizar LAST para un cursor FORWARD_ONLY, se devuelve un mensaje de error porque FORWARD_ONLY solo permite el desplazamiento en una dirección.
  0x10	ABSOLUTE	Captura un búfer de nrows filas a partir de la fila rownum. [!NOTA]    Al usar ABSOLUTE para un cursor DYNAMIC o FORWARD_ONLY, se devuelve un mensaje de error porque FORWARD_ONLY solo permite el desplazamiento en una dirección.
  0x20	RELATIVE	Captura el búfer de nrows filas a partir de la fila que se especifica como que es el valor rownum de filas a partir de la primera fila del bloque actual. En este caso rownum puede ser un número negativo. [!NOTA]    Al utilizar RELATIVE para un cursor FORWARD_ONLY, se devuelve un mensaje de error porque FORWARD_ONLY solo permite el desplazamiento en una dirección.
  0x80	REFRESH	Rellena el búfer a partir de las tablas subyacentes.
  0x100	INFO	Recupera información acerca del cursor. Esta información se devuelve utilizando los parámetros nrows y rownum. Por consiguiente, cuando se especifica INFO, rownum y nrows se convierten en parámetros de salida.
  0x200	PREV_NOADJUST	Se utiliza como PREV. Sin embargo, si el principio del conjunto de resultados se encontrara prematuramente, los resultados podrían variar.
  0x400	SKIP_UPDT_CNCY	Se debe utilizar con uno de los otros valores de fetchtype, excepto INFO.

  [!NOTA]

     No se admite el valor 0x40.

  Para obtener más información, vea la sección Comentarios más adelante en este tema.

• rownum
  Es un parámetro opcional que se utiliza para especificar la posición de la fila para los valores ABSOLUTE e INFO de fetchtype utilizando solo valores enteros para la entrada, la salida o ambos. rownum actúa como desplazamiento de fila para el valor de bit de fetchtype RELATIVE. rownum se omite para todos los demás valores. Para obtener más información, vea la sección Comentarios más adelante en este tema.

• nrows
  Es un parámetro opcional que se utiliza para especificar el número de filas que capturar. Si no se especifica un valor para nrows, el valor predeterminado son 20 filas. Para establecer la posición sin devolver los datos, especifica el valor 0. Cuando nrows se aplica a la consulta INFO de fetchtype, devuelve el número total de filas en esa consulta.

  [!NOTA]

     El valor de bit de fetchtype REFRESH omite el valor de nrows.

  Para obtener más información, vea la sección Comentarios más adelante en este tema.

Valores del código de retorno

Al especificar el valor de bit INFO, los valores que se pueden devolver se muestran en las siguientes tablas.

[!NOTA]

Si no se devuelve ninguna fila, el contenido del búfer permanece como estuviera.

Comentarios

Parámetro cursor

Antes de que se produzca ninguna operación de captura, la posición predeterminada de un cursor está antes de la primera fila del conjunto de resultados.

Parámetro fetchtype

Excepto en el caso de SKIP_UPD_CNCY, los valores de fetchtype son mutuamente excluyentes.

Cuando se especifica SKIP_UPDT_CNCY, los valores de columna de marca de tiempo no se escriben en la tabla de conjunto de claves cuando una fila se captura o actualiza. Si la fila del conjunto de claves se está actualizando, los valores de las columnas de marca de tiempo permanecen como el valor anterior. Si se inserta la fila del conjunto de claves, los valores de las columnas de marca de tiempo son indefinidos.

Para los cursores KEYSET, esto significa que la tabla del conjunto de claves tiene el conjunto de valores durante la última operación FETCH sin salto, si se realizó alguna. En otro caso, tiene el conjunto de valores durante el rellenado.

Para los cursores DYNAMIC, esto significa que si el salto se realiza con una actualización, genera los mismos resultados que KEYSET. Para cualquier otro tipo de captura, la tabla de conjunto de claves se trunca. Esto significa que se insertan las filas y que los valores de las columnas de marca de tiempo son indefinidos. Por consiguiente, al ejecutar sp_cursorfetch para los cursores DYNAMIC, evite usar SKIP_UPDT_CNCY para cualquier operación distinta de REFRESH.

Si se produce un error en una operación de captura porque la posición del cursor solicitada está más allá del conjunto de resultados, la posición del cursor se establece justo después de la última fila. Si se produce un error en una operación de captura porque la posición del cursor solicitada está antes del conjunto de resultados, la posición del cursor se establece antes de la primera fila.

Parámetro rownum

Al utilizar rownum, el búfer se llena a partir de la fila especificada.

El valor de fetchtype ABSOLUTE hace referencia a la posición de rownum dentro del conjunto de resultados entero. Un número negativo con ABSOLUTE especifica que la operación cuenta las filas desde el final del conjunto de resultados.

El valor de fetchtype RELATIVE hace referencia a la posición de rownum en relación con la posición del cursor al principio del búfer actual. Un número negativo con RELATIVE especifica que el cursor va atrasado desde la posición del cursor actual.

Parámetro nrows

Los valores de fetchtype REFRESH e INFO omiten este parámetro.

Al especificar el valor FIRST de fetchtype con un valor nrow de 0, el cursor se coloca antes del conjunto de resultados que no tenga ninguna fila en el búfer de captura.

Al especificar el valor LAST de fetchtype con un valor nrow de 0, el cursor se coloca después del conjunto de resultados que no tenga ninguna fila en el búfer de captura actual.

Para los valores de fetchtype NEXT, PREV, ABSOLUTE, RELATIVE y PREV_NOADJUST, el valor 0 para nrow es no válido.

Consideraciones sobre RPC

El estado de retorno de RPC indica si el parámetro de tamaño del conjunto de claves es final o no; es decir, si el conjunto de claves o la tabla temporal se rellenan de forma asincrónica.

El parámetro de estado de RPC se establece en uno de los valores mostrados en la siguiente tabla.

Las filas se devuelven como un conjunto de resultados típico, es decir, formato de columna (0x2a), filas (0xd1), seguido de Done (0xfd). Los tokens de metadatos se envían en el mismo formato que el especificado para sp_cursoropen, es decir: 0x81, 0xa5 y 0xa4 para los usuarios de SQL Server 7.0, etc. Los indicadores de estado de la fila se envían como columnas ocultas, similar al modo BROWSE, al final de cada fila con el nombre de columna rowstat y el tipo de datos INT4. Esta columna rowstat tiene uno de los valores que se muestran en la tabla siguiente.

Dado que el protocolo TDS no proporciona ninguna manera de enviar la columna de estado final sin enviar las columnas anteriores, los datos ficticios se envían para las filas que faltan (los campos que aceptan valores NULL establecidos en null, los campos de longitud fija establecidos en 0 o el valor predeterminado para esa columna, según corresponda).

El número de filas DONE siempre será cero. El mensaje DONE contiene el número de filas del conjunto de resultados real. Entre los mensajes de TDS podrían aparecer mensajes de error o informativos.

Para solicitar que los metadatos acerca de la lista de selección del cursor se devuelvan en la flujo de TDS, establezca en 1 la marca de entrada RPC RETURN_METADATA.

Ejemplos

A.Usar PREV para cambiar una posición del cursor

Suponga que el cursor h2 generaría un conjunto de resultados con el siguiente contenido y una posición actual como la que se muestra:

row 1 contents    
row 2 contents
row 3 contents
row 4 contents  <-- current position
row 5 contents 
row 6 contents

Después, una operación sp_cursorfetch PREV que tiene un valor del parámetro nrows igual a 5 colocaría lógicamente el cursor dos filas antes de la primera fila del conjunto de resultados. En estos casos, el cursor se ajusta para iniciarse en la primera fila y devolver el número de filas solicitadas. Esto suele significar que devolverá las filas que estaban en el búfer de captura PRIOR.

[!NOTA]

 Este es el caso exacto en el que el parámetro de estado de RPC está establecido en 2.

B.Usar PREV_NOADJUST para devolver menos filas que PREV

PREV_NOADJUST nunca incluye ninguna de las filas de la posición del cursor actual o posteriores en el bloque de filas que devuelve. En los casos en los que PREV devuelve las filas después de la posición actual, PREV_NOADJUST devuelve menos filas de las solicitadas en nrows. Dada la posición actual del ejemplo A anterior, cuando PREV se aplica, sp_cursorfetch(h2, 4, 1, 5) captura las siguientes filas:

row1 contents 
row2 contents
row3 contents
row4 contents
row5 contents

Sin embargo, cuando se aplica PREV_NOADJUST, sp_cursorfetch(h2, 512, 6, 5) captura solo las siguientes filas:

row1 contents 
row2 contents
row3 contents 

Vea también

Referencia

sp_cursoropen (Transact-SQL)

Procedimientos almacenados del sistema (Transact-SQL)