sp_cursorfetch (Transact-SQL)
Se aplica a: 
SQL Server
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 ID = 7 en un paquete de flujo de datos tabular (TDS).
Convenciones de sintaxis de Transact-SQL
Sintaxis
sp_cursorfetch cursor
[ , fetchtype [ , rownum [ , nrows ] ] ]
[ ; ]
Argumentos
cursor
Valor de identificador generado por SQL Server y devuelto por sp_cursoropen. cursor es un parámetro necesario que llama a para un valor de entrada int . Para obtener más información, vea la sección Notas.
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 de 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 de nrows . |
0x0004 |
PREV |
Captura el búfer anterior de filas de nrows . Nota: El uso PREV de para un FORWARD_ONLY cursor devuelve un mensaje de error porque FORWARD_ONLY solo admite el desplazamiento en una dirección. |
0x0008 |
LAST |
Captura el último búfer de filas de nrows . Si nrows es igual a 0, el cursor se coloca después del conjunto de resultados y no se devuelve ninguna fila. Nota: El uso LAST de para un FORWARD_ONLY cursor devuelve un mensaje de error porque FORWARD_ONLY solo admite el desplazamiento en una dirección. |
0x10 |
ABSOLUTE |
Captura un búfer de filas de nrows a partir de la fila rownum . Nota: El uso ABSOLUTE de para un DYNAMIC cursor o un FORWARD_ONLY cursor devuelve un mensaje de error porque FORWARD_ONLY solo admite el desplazamiento en una dirección. |
0x20 |
RELATIVE |
Captura el búfer de filas de nrows a partir de la fila especificada como el valor numérico de las filas de la primera fila del bloque actual. En este caso, el número de fila puede ser un número negativo. Nota: El uso RELATIVE de para un FORWARD_ONLY cursor devuelve un mensaje de error porque FORWARD_ONLY solo admite 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 mediante los parámetros rownum y nrows . Por lo tanto, cuando INFO se especifica , rownum y nrows se convierten en parámetros de salida. |
0x200 |
PREV_NOADJUST |
Se usa como PREV. Sin embargo, si el principio del conjunto de resultados se encontrara prematuramente, los resultados podrían variar. |
0x400 |
SKIP_UPDT_CNCY |
Debe usarse con uno de los otros valores fetchtype , excepto para INFO. |
Nota:
No hay compatibilidad con el valor 0x40.
Para obtener más información, vea la sección Notas.
rownum
Parámetro opcional que se usa para especificar la posición de fila para los ABSOLUTE valores y INFO fetchtype usando solo valores enteros para la entrada o salida, o ambos. rownum actúa como desplazamiento de fila para el valor RELATIVEde bit fetchtype . rownum se omite para todos los demás valores. Para obtener más información, vea la sección Notas.
nrows
Parámetro opcional que se usa para especificar el número de filas que se van a capturar. Si no se especifican nrows , el valor predeterminado es 20 filas. Para establecer la posición sin devolver datos, especifique un valor de 0. Cuando nrows se aplica a la consulta fetchtypeINFO, devuelve el número total de filas de esa consulta.
El valor de REFRESH bit fetchtype omite nrows. Para obtener más información, vea la sección Notas.
Valores de código de retorno
Al especificar el valor INFOde bit , los valores que se pueden devolver se muestran en las tablas siguientes.
Si no se devuelve ninguna fila, el contenido del búfer permanece tal como estaban.
| <rownum> | Establecer en |
|---|---|
| Si no está abierto | 0 |
| Si está colocado antes del conjunto de resultados | 0 |
| Si está colocado después del conjunto de resultados | -1 |
Para KEYSET los cursores y STATIC |
Número de fila absoluto de la posición actual en el conjunto de resultados |
Para DYNAMIC cursores |
1 |
Para ABSOLUTE |
-1 devuelve la última fila de un conjunto. -2 devuelve de la segunda a la última fila de un conjunto, etc. Nota: Si se solicita más de una fila para capturar en este caso, se devuelven las dos últimas filas del conjunto de resultados. |
<nrows> |
Establecer en |
|---|---|
| Si no está abierto | 0 |
Para KEYSET los cursores y STATIC |
Normalmente, el tamaño del conjunto de claves actual.-m si el cursor está en creación asincrónica con filas m encontradas en este punto. |
Para DYNAMIC cursores |
-1 |
Comentarios
Parámetro de cursor
Antes de las operaciones de captura, la posición predeterminada de un cursor es antes de la primera fila del conjunto de resultados.
El parámetro fetchtype
Excepto para SKIP_UPD_CNCY, los valores fetchtype son mutuamente excluyentes.
Cuando SKIP_UPDT_CNCY se especifica , los valores de columna de marca de tiempo no se escriben en la tabla de conjunto de claves cuando se captura o actualiza una fila. 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.
En KEYSET el caso de los cursores, esto significa que la tabla de conjunto de claves tiene los valores establecidos durante el último noskip FETCH, si se realizó uno. Si no es así, es el valor establecido durante el rellenado.
En DYNAMIC el caso de los cursores, esto significa que si la omisión 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 las filas se están insertando y los valores de las columnas de marca de tiempo no están definidos. Por lo tanto, cuando se ejecuta sp_cursorfetch para DYNAMIC cursores, 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
Cuando se usa rownum, el búfer se rellena a partir de la fila especificada.
El valor ABSOLUTE fetchtype hace referencia a la posición de rownum dentro del conjunto de resultados completo. Un número negativo con ABSOLUTE especifica que la operación cuenta filas desde el final del conjunto de resultados.
El valor RELATIVE fetchtype hace referencia a la posición de rownum en relación con la posición del cursor al principio del búfer actual. Número negativo con RELATIVE especifica que el cursor retrocede desde la posición actual del cursor.
Parámetro nrows
Los valores REFRESH fetchtype y INFO omiten este parámetro.
Cuando se especifica un valor fetchtype de FIRST que es un valor de nrow de 0, el cursor se coloca antes del conjunto de resultados que no es ninguna fila en el búfer de captura.
Cuando se especifica un valor fetchtype de LAST que es un valor de nrow de 0, el cursor se coloca después del conjunto de resultados que no tiene filas en el búfer de captura actual.
Para los valores fetchtype de NEXT, PREV, ABSOLUTERELATIVE, y PREV_NOADJUST, un valor de nrow de 0 no es válido.
Consideraciones sobre RPC
El estado devuelto 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.
| Valor | Descripción |
|---|---|
0 |
El procedimiento se ejecutó correctamente. |
0x0001 |
Se produjo un error en el procedimiento. |
0x0002 |
Una captura en una dirección negativa hizo que la posición del cursor se estableciera al principio del conjunto de resultados, cuando la captura habría estado lógicamente antes que los resultados. |
0x10 |
Se cerró automáticamente un cursor de avance rápido. |
Las filas se devuelven como un conjunto de resultados típico: formato de columna (0x2a), filas (0xd1), seguidas de DONE (0xfd). Los tokens de metadatos se envían en el mismo formato que se especifica para sp_cursoropen: 0x810xa5 y 0xa4 para los usuarios de SQL Server, etc. Los indicadores de estado de fila se envían como columnas ocultas, de forma similar al BROWSE modo, al final de cada fila con el nombre de columna rowstat y el tipo de datos int. Esta columna rowstat tiene uno de los valores que se muestran en la tabla siguiente.
| Valor | Descripción |
|---|---|
0x0001 |
FETCH_SUCCEEDED |
0x0002 |
FETCH_MISSING |
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 se establecen en NULL y los campos de longitud fija se establecen 0en , en blanco o en el valor predeterminado de esa columna, según corresponda.
El DONE recuento de filas siempre 0es . El DONE mensaje contiene el recuento de filas del conjunto de resultados real y los mensajes informativos o de error pueden aparecer entre los mensajes de TDS.
Para solicitar que los metadatos sobre la lista de selección del cursor se devuelvan en el flujo de TDS, establezca la marca 1de entrada RPC RETURN_METADATA en .
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
A continuación, un sp_cursorfetch PREV donde nrows es 5 colocar 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 devuelve filas que estaban en el PRIOR búfer de captura.
Nota:
Este es el caso exacto en el que el parámetro de estado de RPC está establecido en 2.
B. Use PREV_NOADJUST para devolver menos filas que prev
PREV_NOADJUST nunca incluye ninguna de las filas en o después de la posición actual del cursor en el bloque de filas que devuelve. En los casos en PREV los que devuelve 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, cuando PREV se aplica, sp_cursorfetch (h2, 4, 1, 5) captura las filas siguientes:
row1 contents
row2 contents
row3 contents
row4 contents
row5 contents
Sin embargo, cuando PREV_NOADJUST se aplica, sp_cursorfetch (h2, 512, 6, 5) solo captura las siguientes filas:
row1 contents
row2 contents
row3 contents